Webhooks are a way to interact between your app and Document changes.

Webhook events:

• document_save: Every time you save a document
• document_create: The first time you create a document
• document_publish: When you publish a document
• document_unpublish: When you unpublish a document
• document_trash: When you move a document to the trash

When you are applying document changes in bulk, only one webhook will be sent containing an array of the affected documents.

This is an example of the webhook's payload format:

{
  "event": "document_save",
  "data": {
    "type": "document_save",
    "eventId": "d27ac990-f645-4f8a-ae30-9b303e4de251",
    "requestId": "6511af19-eead-43be-8b56-c35dfd3415da",
    "documentIds": [
      "da90646e-50fb-4795-a752-0a24d38a5ed0"
    ]
  }
}

The requestId is the Id for the request responsible for triggering the webhook. This id is also used in the audit logs in case you want to trace back what happened.

The eventId is unique per webhook event. You can also use this value as an idempotency-key to avoid duplicate deliveries.

Validate Endpoint

The first time you add a webhook POST url, the system required to verify it by sending a secret token to that address. You have to manually copy and paste it back to the UI proving that you have control of that url.

Signed Requests

You can optionally sign webhooks by adding a secret (min. 8 characters). If you leave the secret field empty then the request will be delivered unsigned.

Otherwise, the system will send a post request that will contain a header called Signature. The receiving app can use this header to verify the payload hasn't been tampered with.

To calculate the signature value you have to compute a Hash-based message authentication code (HMAC) using your secret with sha256 algorithm.

node.js example:

const signature = crypto.createHmac('sha256', secret)
      .update(JSON.stringify(req.body))
      .digest("hex");

php example:

$payloadJson = json_encode($payload); 
$signature = hash_hmac('sha256', $payloadJson, $secret);