API reference

Webhook endpoints

Where we send signed event notifications. See the Webhooks guide.

Endpoints · 9

POST Add an endpoint
GET Retrieve an endpoint
GET List endpoints
PATCH Update an endpoint
DELETE Delete an endpoint
POST Rotate the signing secret
POST Send a test event
GET List deliveries
POST Retry a delivery

The object

Field	Type	Description
`id`	string	Unique ID, starting with whk_.
`object`	string	Always "webhook".
`url`	string	A public HTTPS address.
`description`	string	Up to 200 characters.
`events`	array	Event types, or ["*"] for all.
`enabled`	boolean	Turned-off endpoints get nothing.
`secret`	string	The signing secret (whsec_…). Returned when you create or retrieve one endpoint, not in lists.
`created_at`	timestamp

POST/webhooks

Add an endpoint

Parameter	Type		Description
`url`	string	required	Public HTTPS.
`events`	array	required	One or more event types, or "*".
`description`	string	optional

Request

bash

curl -X POST "https://api.esorasign.com/v1/webhooks" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/esora/webhooks", "events": ["document.completed", "recipient.signed"], "description": "Production CRM sync" }'

Response

json

{
  "id": "whk_1ZHu8qRtZHjQMhuOzE95B9",
  "object": "webhook",
  "url": "https://example.com/esora/webhooks",
  "description": "Production CRM sync",
  "events": ["document.completed", "recipient.signed"],
  "enabled": true,
  "secret": "whsec_kQ3m...",
  "created_at": "2026-11-01T12:00:00.000Z"
}

GET/webhooks/{id}

Retrieve an endpoint

Includes the signing secret.

Request

bash

curl "https://api.esorasign.com/v1/webhooks/whk_1ZHu8qRtZHjQMhuOzE95B9" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "id": "whk_1ZHu8qRtZHjQMhuOzE95B9",
  "object": "webhook",
  "url": "https://example.com/esora/webhooks",
  "description": "Production CRM sync",
  "events": ["document.completed", "recipient.signed"],
  "enabled": true,
  "secret": "whsec_kQ3m...",
  "created_at": "2026-11-01T12:00:00.000Z"
}

GET/webhooks

List endpoints

Newest first. Secrets are not included.

Parameter	Type		Description
`limit`	integer	optional	How many objects to return, 1 to 100. Default 20.
`starting_after`	string	optional	The next_cursor from the previous page. Leave it out for the first page.

Request

bash

curl "https://api.esorasign.com/v1/webhooks" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "whk_1ZHu8qRtZHjQMhuOzE95B9",
      "object": "webhook",
      "url": "https://example.com/esora/webhooks",
      "description": "Production CRM sync",
      "events": ["document.completed", "recipient.signed"],
      "enabled": true,
      "created_at": "2026-11-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

PATCH/webhooks/{id}

Update an endpoint

Parameter	Type		Description
`url, events, description`		optional
`enabled`	boolean	optional	false pauses deliveries.

Request

bash

curl -X PATCH "https://api.esorasign.com/v1/webhooks/whk_1ZHu8qRtZHjQMhuOzE95B9" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Response

json

{
  "id": "whk_1ZHu8qRtZHjQMhuOzE95B9",
  "object": "webhook",
  "url": "https://example.com/esora/webhooks",
  "description": "Production CRM sync",
  "events": ["document.completed", "recipient.signed"],
  "enabled": false,
  "created_at": "2026-11-01T12:00:00.000Z"
}

DELETE/webhooks/{id}

Delete an endpoint

Request

bash

curl -X DELETE "https://api.esorasign.com/v1/webhooks/whk_1ZHu8qRtZHjQMhuOzE95B9" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{ "id": "whk_1ZHu8qRtZHjQMhuOzE95B9", "object": "webhook", "deleted": true }

POST/webhooks/{id}/rotate-secret

Rotate the signing secret

Returns the new secret. For 24 hours deliveries carry signatures with both secrets.

Request

bash

curl -X POST "https://api.esorasign.com/v1/webhooks/whk_1ZHu8qRtZHjQMhuOzE95B9/rotate-secret" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "id": "whk_1ZHu8qRtZHjQMhuOzE95B9",
  "object": "webhook",
  "url": "https://example.com/esora/webhooks",
  "description": "Production CRM sync",
  "events": ["document.completed", "recipient.signed"],
  "enabled": true,
  "secret": "whsec_kQ3m...",
  "previous_secret_expires_at": "2026-11-04T12:00:00.000Z",
  "created_at": "2026-11-01T12:00:00.000Z"
}

POST/webhooks/{id}/test

Send a test event

Sends a webhook.test event now, signed like any other, and reports how your endpoint answered.

Request

bash

curl -X POST "https://api.esorasign.com/v1/webhooks/whk_1ZHu8qRtZHjQMhuOzE95B9/test" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{ "object": "webhook_test", "ok": true, "response_status": 200, "error": null }

GET/webhooks/{id}/deliveries

List deliveries

The last 100 deliveries to this endpoint, newest first. status is pending, succeeded or failed.

Request

bash

curl "https://api.esorasign.com/v1/webhooks/whk_1ZHu8qRtZHjQMhuOzE95B9/deliveries" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "dlv_3gE0VrbBGI09QYNdaKy8is",
      "object": "webhook_delivery",
      "event_id": "evt_5ydfhl3TvtnythpZPPPP6U",
      "event_type": "document.completed",
      "status": "succeeded",
      "attempts": 1,
      "response_status": 200,
      "error": null,
      "created_at": "2026-11-03T09:41:28.000Z",
      "delivered_at": "2026-11-03T09:41:28.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/webhooks/{id}/deliveries/{delivery_id}/retry

Retry a delivery

Queues the delivery again with a fresh set of attempts.

Request

bash

curl -X POST "https://api.esorasign.com/v1/webhooks/whk_1ZHu8qRtZHjQMhuOzE95B9/deliveries/dlv_3gE0VrbBGI09QYNdaKy8is/retry" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{ "id": "dlv_3gE0VrbBGI09QYNdaKy8is", "object": "webhook_delivery", "status": "pending" }