# Webhooks

Webhooks allow you to subscribe to certain events on your Signicat account. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL.

# Webhook events

When configuring a webhook, you can choose which events you would like to subscribe to.

# Signature events

The following events are available in our Signature API.

Type Description
document_before_deleted A document is about to be deleted
document_canceled A document was canceled
document_created A new document has been created
document_deleted A document was deleted
document_expired A document has expired and can no longer be signed
document_email_opened A signer opened a document email
document_link_opened A document / signer link was opened
document_packaged A document was packaged with all required signatures
document_partially_signed A document retrieved a new signature
document_read A document was read by a signer
document_signed A document retrieved all required signatures

# Shared events

The following events are available in multiple APIs:

Type Description
resource_created A resource was created and is available for download

# Person monitor events

The following events are available in our Person API:

Type Payload
person_monitor_changes New changes were added to the monitor

# Wildcard event

We also support a wildcard (*) that will subscribe you to all events (including all new events in the future).

Adding the wildcard event to an existing webhook will remove the existing specific events.

# Creating webhooks

Webhooks can be created and managed through our REST API, or directly from the Signicat Express Dashboard. (opens new window)

# Ping event

When you create a new webhook, we'll send you a ping event to make sure your webhook endpoint is set up correctly.

This event is not stored and can not be retrieved via the REST API. A ping can also be triggered manually by using the ping endpoint, or directly from the Signicat Dashboard.

# Required 2XX success response

To acknowledge that you received the webhook without any problems, your server should return a 200 OK HTTP status code. Any response code outside the 200 range will indicate that you did not receive the webhook.

Signicat expects a response within 10 seconds of sending the webhook event.

Delivery failures are retried 7 times with exponential backoff. The last retry will happen approximately 45 hours after the initial attempt.

# Securing your webhooks

By default, a webhook endpoint is open and may receive a payload from anybody who knows the URL. For security reasons, we recommend you to ensure that the data is coming from Signicat. This can be done by setting up a secret token and use it to validate the payload.

# Creating your secret token

A secret token can be added to your webhook from the Signicat Dashboard or by using the webhooks endpoint. It is recommended that you use a random string with high entropy.

# Validating payloads

Using your secret token, we create an HMAC-SHA256 signature of the request body. All requests include an X-Idfy-Signature header containing this signature, which you then can use to validate the integrity of the payload and its origin.

To validate the request, compute the HMAC digest using your secret token as the signing key and ensure that it matches the signature from the header. Below is an example of how this can be done with Node.js:

const crypto = require('crypto');
const secret = 'your-secret-token';

// It is important to use raw request body and not deserialize it 
const payload = '{"message":"Hello, world"}';

const hmac = crypto.createHmac('sha256', secret);
const signature = hmac.update(payload).digest('hex');
console.log(signature) // => def564b8df06ae55c788493cb414068b2cf017385d96ecb39aa3e844fdbbcdea
Last updated: 06/03/2024 09:30 UTC