Webhooks

At Resly, we are proud to offer seamless integration with our state-of-the-art webhook support. Our system allows users to effortlessly subscribe to a variety of events, ensuring that you stay up-to-date with real-time information and data exchange. Understanding the importance of reliability, we have implemented a robust failover mechanism to keep your operations running smoothly. In the event of a server failure, our exponential backoff strategy kicks in, intelligently retrying requests at increasing intervals. This approach reduces the strain on your system and guarantees a consistent and dependable experience with Resly's webhooks.

Getting Started

To fully harness the power of Resly's webhook support, you will need to manage your webhooks by creating, selecting triggers, editing, and deleting them as needed. All of these actions can be performed under the "Webhooks" section within the "Settings" page in your team area.

To get started, follow these steps:

  • Navigate to "Settings" in the main menu.
  • Locate the "Webhooks" section.
  • To create a new webhook, click the "Create New Webhook" button and enter the necessary information, such as a descriptive name, the target URL and the triggers that determine which events will cause the webhook to fire.
  • If you need to edit an existing webhook, click the "Edit" button next to the webhook you want to modify.

By following these simple steps, you can efficiently manage your webhooks and ensure that your system stays informed about the events most relevant to your needs.

📘

Additionally, we would like to inform you that when new triggers are released, they will not be automatically added to your existing webhooks. This is an intentional design choice to ensure that we do not inadvertently cause any disruptions or breakages in your existing code. By taking this manual approach, we prioritize the stability and integrity of your system, ensuring a smooth and consistent experience when using Resly's webhook support.

The request [POST]

Please note that our system will always send a POST request to the specified endpoint, containing a JSON payload with the following format:

{  
  "teamId": "The unique identifier of your team",  
  "event": "The event key corresponding to one of the subscribed triggers",  
  "objectType": "The type of object associated with the event, as per the list of available object types",  
  "objectId": "The unique identifier of the object related to the event",  
  "object": "The full object, providing all relevant data and details",
  "requestAt": "ISO time of the request",
  "hash": "SHA-265 hash of the request exluding the hash and signature fields",
  "signature": "RSA-SHA256 encyption of the hash value, find public key below in the section: Message integrity"
}

By maintaining this standardized format, Resly ensures a consistent and predictable experience for developers. Make sure to adapt your receiving endpoint to process the webhook notifications according to this JSON structure.

Available events

Event nameDescriptionType
ENVELOPE_SEALEDThis events is triggered when all signees have signed the document(s) and Resly has sealed it.ENVELOPE
ENVELOPE_CREATEDnot public, coming soonENVELOPE
ENVELOPE_DELETEDnot public, coming soonENVELOPE
ENVELOPE_UPDATEDnot public, coming soonENVELOPE
ENVELOPE_SEAL_FAILEDnot public, coming soonENVELOPE
SIGNEE_SIGNEDnot public, coming soonSIGNEE
SIGNEE_INVITEDnot public, coming soonSIGNEE
SIGNEE_REMINDEDnot public, coming soonSIGNEE
SIGNEE_BOUNCEnot public, coming soonSIGNEE
SIGNEE_OPENEDnot public, coming soonSIGNEE
SIGNEE_CREATEDnot public, coming soonSIGNEE
SIGNEE_UPDATEDnot public, coming soonSIGNEE
SIGNEE_DELETEDnot public, coming soonSIGNEE
FILE_UPLOADEDnot public, coming soonFILE
FILE_DELETEDnot public, coming soonFILE
FILE_UPDATEDnot public, coming soonFILE

Available objectTypes

Event nameDescription
ENVELOPEMore info about the object fields here. Click the 200 response to view the details.
SIGNEEnot implemented, coming soon
FILEnot implemented, coming soon
FORMnot implemented, coming soon

Error management

Exponential backoff is a strategy used to space out retries of failed requests with increasing intervals. This approach helps reduce the load on the server and the likelihood of further failures due to congestion. The backoff factor and the number of retries are important parameters in determining the delay between each retry attempt.

We have implemented an exponential backoff with a factor of 4, a total of 17 retries, and an initial interval of 60 seconds. The raw formula is as follows: (60 + amountOfRequests ^ factor).

Here's a breakdown of how this works:

  • After the first failed request, the system waits for the initial interval of 60 seconds before making the first retry attempt.
  • For each subsequent retry, the delay between attempts is calculated using the provided formula, where amountOfRequests is the number of failed requests (including the current one), and factor is the backoff factor (4 in this case).

📘

To provide a clearer picture, let's look at the first few retries and their respective intervals:

Retry 1 (1 failed request): 60 + 1 ^ 4 = 61s after first request
Retry 2 (2 failed requests): 60 + 2 ^ 4 = 76s after first request
Retry 3 (3 failed requests): 60 + 3 ^ 4 = 141s after first request
Retry 4 (4 failed requests): 60 + 4 ^ 4 = 316s after first request
...
Retry 17 (last ): 60 + 17 ^ 4 = 83581s after first request (about 24h)

Note: The times above can differ from 1s to 60s based since our server only handle request with a 60s interval.

The time between retries increases as a function of the number of failed requests raised to the power of the backoff factor. In this specific configuration, the delay between retry attempts will grow more gradually compared to the traditional exponential backoff approach.

By using this modified exponential backoff strategy with a factor of 4, 17 retries, and a 60-second initial interval, we ensure a more efficient and less intrusive way of handling failed requests while minimizing the risk of overwhelming the server.

Message integrity

To verify that the request is from Resly we recommend to check the signature field in the request data with the public key below. The result should match the exact value of the hash field. Signature was created using RSA-SHA256.

  1. Get the raw JSON response body.
  2. Remove the "hash" and "signature" fields from the response. Run the remaining body through a SHA256 hasher with HEX as output. The result should match the hash provided in the original body.
  3. Verify the hash against the signature and Public Key.

NodeJS example below using built-in crypto library.

import crypto from 'crypto'

// Save signature data from response body
const {signature} = body

// Calculate hash of body content without signature and hash fields
delete body.signature
delete body.hash
const calculatedHash = crypto.createHash('sha256').update(JSON.stringify(body)).digest('hex')

// NodeJS crypto library requires signature data as buffer
const signatureBuffer = Buffer.from(signature, 'base64')

const isValid = crypto.verify('RSA-SHA256', calculatedHash, PUBLIC_KEY, signatureBuffer)

console.log(isValid) // true / false

-----BEGIN PUBLIC KEY-----
MIIBITANBgkqhkiG9w0BAQEFAAOCAQ4AMIIBCQKCAQBnuGCVYWPuIwLjHvWx0t41
h6mbHnPzBVqQZBDtxLp0rQGutsB9968fFPgJYX//N5s1pNvyTbIihQEVPVGoEgud
OToATIi9Vr4XIjBfj9QecpCvvCocJ/Q8ni3ob/etsLA4V20wTQdgyOB6Av1eGy7B
2HLkcjm3iTfHYANOLne2nyS+jq0ufW4zdYmziT/pBi4v25wSUDfIyx0UaMWTo6Ep
2NXZxOGJ5O0hFKnjZr8TSDUE7LFk4WigsyuiSUx0u2LEwE90XKs+YMEdvZyiwaIE
WYHcZCyRoGJ5QctFTOyifRiaFONple9ME2N17m1KepZ7yr860c0zwPrTYHDG6Mmh
AgMBAAE=
-----END PUBLIC KEY-----

Recommendations

As we continue to enhance and expand our webhook support, you can expect more events and object types to be added in the future. With this in mind, it is essential that you design and implement your webhook handling code to be flexible and easily adaptable to accommodate these forthcoming additions.

When implementing your webhook processing logic, consider the following best practices:

  • Make your code modular and use a scalable architecture that allows you to easily add or modify event and object type handlers.
  • Avoid hardcoding event or object type-specific logic, as this can make it difficult to update your code when new events or object types are introduced.
  • Regularly check for updates on our platform, and stay informed about the latest events and object types being added to Resly's webhook support.
  • Test your webhook handling code thoroughly to ensure compatibility and proper functioning with both existing and newly introduced events and object types.

By keeping these best practices in mind, you can create a more robust and future-proof webhook handling system, ensuring seamless integration with Resly's webhook support as it evolves over time.

Support

At Resly, we are committed to providing exceptional support to help you make the most of our platform. If you have any questions, concerns, or issues, please don't hesitate to reach out to us through one of the following channels:

Our team is eager to assist you, and we love solving problems to ensure a seamless experience with Resly. If you encounter any issues with a webhook, we advise against deleting the webhook until our support team has had an opportunity to review the problem and provide guidance.

Additionally, we are always looking to enhance our platform and services. If you find that you are missing a particular feature, please let us know. Your feedback is invaluable in helping us improve and cater to the needs of our users.

👍

Remember, our team is here to help, and we are just a call, email, or chat away!