Webhooks

Webhooks are a powerful tool for automating and streamlining communication between different web applications. Think of a webhook as an HTTP callback that enables one application to send real-time data to another whenever a specific event occurs.

At Circularo, we’ve implemented webhooks to trigger on document events. Whenever one of the following events is triggered, a POST request is sent to a predefined callback URL, ensuring your application stay in sync effortlessly.

Webhooks need to be activated by our support team before you can use them. To get started, please reach out to our support team at support@circularo.com.

Document events

• documentCreated: Triggers whenever a new document is created in the system.

• documentEdited: Triggers whenever a document is edited.

• documentDeleted: Triggers whenever a document is deleted.

• signRequest: Triggers whenever a sign request is created for a document.

• signDelegated: Triggers whenever a sign request is delegated for a document.

• signRejected: Triggers whenever a sign request is rejected for a document.

• signExpired: Triggers whenever a sign request expires for a document.

• signCancelled: Triggers whenever a sign request is cancelled for a document.

• documentSigned: Triggers whenever a document is signed.

• documentCompleted: Triggers whenever a document is completed.

• documentSimpleActionExecuted: Triggers whenever a simple action (approve, review, accept) is executed on a document.

HMAC

To prevent spoofing attacks, Circularo supports using HMAC to compute a hash signature for the callback payload. Usage of HMAC is optional.

To use the HMAC, specify the hmacSecret field when creating the webhook. HMAC uses SHA256 algorithm, hexadecimal encoding and is computed over complete payload buffer. HMAC hash will be presented in a header as x-circularo-signature.

To verify that callback request really comes from Circularo, you have to create your own HMAC hash over received payload buffer (using SHA256, hexadecimal encoding) and check that this hash signature matches the signature you received in the header.

Receiving Circularo webhook callback

When a document event is triggered, you will receive a POST request to the specified callback URL. The payload of the callback request will look like this:

{
  "documentId": "9ff53f87-e82b-472b-908e-ad1fd298ac58",  // Trigerring document
  "event": "documentCreated",  // Name of the trigger event from the list above
  "actor": "teamUser",  // User who caused the trigger
  "timestamp": "2024-06-01T13:10:10.500Z"
}