Skip to content
FirmEasy
← Inicio

Create Webhook

POST
https://app.firmeasy.legal/api/v1/webhooks

Create Webhook

Section titled “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?

Section titled “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.

curl -X POST https://app.firmeasy.legal/api/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
Required Fields

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

Required Headers

Section titled “Required Headers”
Authorization
string
Access token obtained during login, with the 'Bearer' prefix.
Limits:Required
Content-Type
string
Specifies the content type of the HTTP request body. For requests that include JSON data
Limits:'application/json'

Request Body (Parameters)

Section titled “Request Body (Parameters)”
target_url
string
Destination URL to which events will be sent when the trigger occurs.
Limits:Required
event
string
Event that will trigger the webhook. E.g.: 'document_signed' or 'signer_rejected'.
Limits:Required

Request Example

Section titled “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

Section titled “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"
}
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

Section titled “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.