Create Webhook

POST {{base_url}}/v1/webhooks

curl -X POST {{base_url}}/v1/webhooks \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "target_url": "https://hooks.yourcompany.com/events/firmeasy",
  "event": "document_signed"
}'

Sin ejecutar·latencia ~ 412 ms

Demo pública · no guarda datos · firma con sandbox PKI

Create Webhook

Allows you to register a webhook to receive automatic notifications when a specific event occurs (for example, when a document is signed or a signer rejects).

When creating the webhook, Firmeasy returns a unique secret_key. This secret will be used to sign all payloads sent to the target_url, allowing authenticity verification via HMAC-SHA256.

Why do we use HMAC?

The HMAC (Hash-based Message Authentication Code) standard is used to guarantee the integrity and authenticity of notifications sent to your target_url.

When Firmeasy fires a webhook, it calculates a hash of the content (payload) using your webhook’s unique secret_key. This allows:

✅ Ensure the request was actually sent by Firmeasy.
✅ Verify that the content was not altered in transit.
✅ Reject unsigned or tampered messages.

To implement validation on your receiving server, you only need to recalculate the HMAC with your secret key (secret_key) and compare the result with the hash received in the header. This way you can have complete confidence in the event’s integrity.

Required Fields

Fields marked with an asterisk (*) are required and must be provided in the request. Other fields are optional.

Required Headers

Parameter	Type	Description	Limits
`Authorization*`	string	Access token obtained during login, with the 'Bearer' prefix.	Required
`Content-Type`	string	Specifies the content type of the HTTP request body. For requests that include JSON data	'application/json'

Request Body (Parameters)

Parameter	Type	Description	Limits
`target_url*`	string	Destination URL to which events will be sent when the trigger occurs.	Required
`event*`	string	Event that will trigger the webhook. E.g.: 'document_signed' or 'signer_rejected'.	Required

Request Example

{
  "target_url": "[https://hooks.empresaglobal.com/events/9d4f7a2c-35e1-4a8b-9216-bc0f3f6b2b93](https://hooks.empresaglobal.com/events/9d4f7a2c-35e1-4a8b-9216-bc0f3f6b2b93)",
  "event": "signer_rejected"
}

Response Example

{
  "id": "c4e51f28-7a91-45c0-a918-2b84f8a14e57",
  "user": "6b2fcd91-3d78-4a19-80fa-50d2ac93e481",
  "document": null,
  "event": "signer_rejected",
  "target_url": "[https://hooks.empresaglobal.com/events/c4e51f28-7a91-45c0-a918-2b84f8a14e57](https://hooks.empresaglobal.com/events/c4e51f28-7a91-45c0-a918-2b84f8a14e57)",
  "active": true,
  "secret_key": "92JF4PLX8MK1S0AGB2VY5HQ7N",
  "custom_headers": null,
  "signed_headers": null,
  "type": "E",
  "created_at": "2024-12-18T10:22:45.000000Z",
  "updated_at": "2024-12-18T10:22:45.000000Z"
}

Nombre	Type	Description
`id`	string	Unique webhook identifier in Firmeasy.
`user`	string	ID of the user who owns the webhook.
`document`	string/null	Associated document if applicable, or null.
`event`	string	Configured event that will trigger the webhook.
`target_url`	string	Configured destination URL.
`active`	boolean	Indicates if the webhook is active.
`secret_key`	string	Unique secret key used to sign payloads with HMAC.
`custom_headers`	object/null	Custom headers if applicable, or null.
`signed_headers`	array/null	Signed headers (currently null).
`type`	string	Configured webhook type.
`created_at`	datetime	Creation date.
`updated_at`	datetime	Last update.

Possible Errors

Code	Status	Description
`400`	Bad Request	Invalid or missing parameters.
`401`	Unauthorized	Unauthorized. Invalid or missing token.
`409`	Conflict	Conflict. Duplicate webhook.
`422`	Unprocessable Entity	Validation error in the sent data.
`500`	Internal Server Error	Unexpected internal error.