# 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