Hooks API

GET /hooks

List webhook callbacks

The workspace's compatibility callbacks. Endpoints created here receive every event and are active immediately, with no ping. Signclad's own webhook management, with per-event subscriptions, secrets, health, and delivery logs, is at /webhook_endpoints; the same endpoints appear in both listings.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/hooks \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

[
  {
    "id": "6d2f8b31-7a4c-4e19-9c53-0f8a1b2c3d4e",
    "callback_url": "https://app.example.com/webhooks/signclad"
  }
]

POST /hooks

Create a webhook callback

Registers a callback URL. Every event is delivered to it. The id is also the key of the compatibility event.hash, so store it.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/hooks \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "callback_url": "https://app.example.com/webhooks/signclad"
}'

DELETE /hooks/{id}

Delete a webhook callback

Stops delivery immediately. Undelivered events are dropped.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X DELETE https://api.signclad.com/api/v1/hooks/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /webhook_endpoints

List webhook endpoints Extension

Every endpoint in the workspace, including those registered through the compatibility POST /hooks route, with subscriptions and current health.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Query parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/webhook_endpoints \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /webhook_endpoints

Create a webhook endpoint Extension

Creates an endpoint with its own signing secret and event subscriptions. The secret is returned once, on creation and on rotation, and never again. verify: true sends a ping first and activates the endpoint only if it answers 2xx.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/webhook_endpoints \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://app.example.com/webhooks/signclad",
  "description": "Production receiver",
  "event_types": [
    "document_completed",
    "document_declined",
    "document_error"
  ],
  "include_test_mode": false,
  "verify": true
}'

GET /webhook_endpoints/{id}

Get a webhook endpoint Extension

The endpoint with its subscriptions, health, and delivery metrics.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/webhook_endpoints/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "id": "6d2f8b31-7a4c-4e19-9c53-0f8a1b2c3d4e",
  "url": "https://app.example.com/webhooks/signclad",
  "description": "Production receiver",
  "event_types": [
    "document_completed",
    "document_declined",
    "document_error"
  ],
  "api_application_id": null,
  "include_test_mode": false,
  "status": "active",
  "secret_last_rotated_at": "2026-08-20T14:03:22Z",
  "created_at": "2026-04-02T08:15:00Z",
  "updated_at": "2026-09-09T17:44:10Z",
  "health": {
    "state": "healthy",
    "consecutive_failures": 0,
    "success_rate_1h": 1,
    "success_rate_24h": 0.998,
    "p95_latency_ms": 210,
    "last_success_at": "2026-09-09T17:43:58Z",
    "last_failure_at": "2026-09-08T22:11:04Z",
    "last_failure_reason": "502 Bad Gateway",
    "pending_count": 0
  }
}

PUT /webhook_endpoints/{id}

Update a webhook endpoint (PUT alias) Extension

The same operation as PATCH, accepted as PUT for clients whose HTTP layer cannot send a PATCH. It is still a partial update: only the properties present are changed.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X PUT https://api.signclad.com/api/v1/webhook_endpoints/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

PATCH /webhook_endpoints/{id}

Update a webhook endpoint Extension

Changes the URL, description, subscriptions, test-mode inclusion, or active state. Pausing an endpoint keeps its events queued for replay; disabling drops them.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X PATCH https://api.signclad.com/api/v1/webhook_endpoints/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

DELETE /webhook_endpoints/{id}

Delete a webhook endpoint Extension

Deletes the endpoint and its queued deliveries. Delivery logs are kept 30 days.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X DELETE https://api.signclad.com/api/v1/webhook_endpoints/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /webhook_endpoints/{id}/rotate_secret

Rotate the signing secret Extension

Issues a new secret and keeps the old one valid for an overlap window, so both signatures verify while the receiver is redeployed. Deliveries during the overlap carry two v1 signature values, one per secret.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/webhook_endpoints/{id}/rotate_secret \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (201)

{
  "id": "6d2f8b31-7a4c-4e19-9c53-0f8a1b2c3d4e",
  "secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "previous_secret_expires_at": "2026-09-10T17:44:10Z"
}

GET /webhook_endpoints/{id}/health

Get endpoint health Extension

Current health state and the counters behind it. healthy → degraded (3 consecutive failures, or over 10% failures in an hour) → failing (25 consecutive failures, or 100% over 24 hours) → disabled (5 days of continuous failure). While failing, attempts are skipped and the endpoint is probed hourly.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/webhook_endpoints/{id}/health \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /webhook_endpoints/{id}/ping

Send a test event Extension

Delivers a synthetic event synchronously and returns what the endpoint answered. Pass event_type to send a realistic sample of that event instead of ping.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/webhook_endpoints/{id}/ping \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "delivered": true,
  "status_code": 200,
  "latency_ms": 143,
  "response_excerpt": "{\"ok\":true}",
  "delivery_id": "whd_01J9K3P2S5N7Q8R1T2V3W4X5"
}

GET /webhook_endpoints/{id}/deliveries

List deliveries Extension

The delivery log: every attempt with its request headers and body, response status and body excerpt, and latency. Dead letters are kept 30 days.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Query parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/webhook_endpoints/{id}/deliveries \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "next_cursor": "eyJpZCI6IndoZF8wMUo5SzNQMlM1TjdROCJ9",
  "has_more": true,
  "data": [
    {
      "id": "whd_01J9K3P2S5N7Q8R1T2V3W4X5",
      "webhook_endpoint_id": "6d2f8b31-7a4c-4e19-9c53-0f8a1b2c3d4e",
      "event_id": "evt_01J9K3P2S5N7Q8R1T2V3W4X5",
      "event_type": "document_completed",
      "document_id": "8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60",
      "status": "failed",
      "next_retry_at": "2026-09-09T18:00:00Z",
      "delivered_at": null,
      "created_at": "2026-09-09T17:44:15Z",
      "request_headers": {
        "X-Signclad-Event": "document_completed",
        "X-Signclad-Event-Id": "evt_01J9K3P2S5N7Q8R1T2V3W4X5",
        "X-Signclad-Delivery": "whd_01J9K3P2S5N7Q8R1T2V3W4X5",
        "X-Signclad-Attempt": "2",
        "X-Signclad-Signature": "t=1789050255,v1=6f4a9c2e8b1d3f5a7c9e0b2d4f6a8c1e3b5d7f9a0c2e4b6d8f0a2c4e6b8d0f2a"
      },
      "attempts": [
        {
          "attempt": 1,
          "attempted_at": "2026-09-09T17:44:15Z",
          "status_code": 502,
          "latency_ms": 10021,
          "response_excerpt": "<html>502 Bad Gateway</html>"
        },
        {
          "attempt": 2,
          "attempted_at": "2026-09-09T17:45:15Z",
          "status_code": null,
          "latency_ms": null,
          "error": "Connection timed out after 10000 ms"
        }
      ]
    }
  ]
}

POST /webhook_endpoints/{id}/deliveries/{delivery_id}/replay

Replay a delivery Extension

Re-sends the stored payload. event.id, event.time, and the body are unchanged, so receivers that dedupe by event.id see a duplicate and drop it; the signature timestamp, X-Signclad-Delivery, and X-Signclad-Attempt are fresh.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/webhook_endpoints/{id}/deliveries/{delivery_id}/replay \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /events

Get the event catalog Extension

Every event Signclad emits, what triggers it, what its data.object carries, and a sample payload. Generated from the same source as the delivery pipeline, so it can be trusted to be complete.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/events \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "data": [
    {
      "type": "document_completed",
      "summary": "Every signer has finished and the document is sealed.",
      "object": "document",
      "compatibility": true,
      "carries_related_signer": true
    }
  ],
  "signature": {
    "header": "X-Signclad-Signature",
    "scheme": "t=<unix>,v1=<hex hmac-sha256(secret, \"<t>.<raw body>\")>",
    "tolerance_seconds": 300,
    "compatibility_hash": "hex(hmac-sha256(key = <endpoint id>, data = \"<type>@<time>\"))"
  },
  "delivery": {
    "timeout_seconds": 10,
    "success": "Any 2xx.",
    "retries": [
      60,
      300,
      900,
      3600,
      10800,
      28800,
      86400,
      172800
    ],
    "dedupe_on": "event.id",
    "order_by": "event.sequence"
  }
}

POST /webhook_endpoints/{id}/enable

Re-enable an endpoint Extension

Brings a paused or disabled endpoint back to active. replay: true also re-queues everything it missed. The offer is returned either way, so a caller can show "312 events are waiting" before deciding.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/webhook_endpoints/{id}/enable \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /webhook_endpoints/{id}/deliveries/{delivery_id}

Get one delivery Extension

One delivery with everything the list form omits: the payload that was sent, the request headers, the response excerpt, and the full attempt timeline. The list omits them because a page of 25 document payloads is megabytes and the list is for scanning.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/webhook_endpoints/{id}/deliveries/{delivery_id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /webhook_endpoints/{id}/replay

Replay a range of deliveries Extension

"Resend everything failed since." since is required: a replay with no floor would re-send a month of history, which is never what anybody meant.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/webhook_endpoints/{id}/replay \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /webhook_inbox

List debugging inboxes Extension

Hosted URLs that record whatever is posted to them, so a developer can see real payloads before writing a receiver.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/webhook_inbox \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /webhook_inbox

Create a debugging inbox Extension

Mints a new inbox and its public URL.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/webhook_inbox \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /webhook_inbox/{id}/requests

Read what an inbox recorded Extension

Everything posted to the inbox, newest first, with headers, query, and body.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Query parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/webhook_inbox/{id}/requests \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /inbox/{token}

Post anything to a debugging inbox Extension

Records the request and answers 200 to anything, whatever the body or content type. A debugging inbox that returned errors would teach the sender the wrong lesson.

Base URL

https://api.signclad.com/api/v1

Authentication

None — this operation is public

Path parameters

Request body

application/json — A object.

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/inbox/{token} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /inbound/postmark

Postmark delivery report Extension

Internal. Bounce, complaint, and delivery reports from Postmark, authenticated by a shared secret in the request rather than by a Signclad credential; the controller refuses by default when that secret is unconfigured, because an unauthenticated bounce endpoint lets a stranger mark any recipient's address dead. Answers 2xx even for a payload it cannot match — an unmatched message id is not an error, it is a message this environment never sent, and a 4xx would make the provider retry and eventually disable the endpoint. A secret that does not check out is 403 invalid_signature in the standard forbidden envelope, matching the SES and Twilio routes. It answered a bare 401 with no code until the error-envelope pass.

Base URL

https://api.signclad.com/api/v1

Authentication

None — this operation is public

Request body

application/json — A object.

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/inbound/postmark \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /inbound/ses

Amazon SES delivery report Extension

Internal. SNS notifications for SES bounces, complaints, and deliveries, authenticated by the SNS message signature plus a topic allowlist. Subscription confirmations are handled here too. Same 2xx-for-anything-unmatched rule as the Postmark route. A signature that does not verify is 403 invalid_signature; a topic that is not in the allowlist is 403 unknown_topic, which is a different fact and gets a different code.

Base URL

https://api.signclad.com/api/v1

Authentication

None — this operation is public

Request body

application/json — A object.

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/inbound/ses \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /inbound/stripe

Stripe webhook Extension

Internal. Billing events from Stripe, authenticated by Stripe-Signature over the raw body. Deduplicated on Stripe's event id, so a redelivery is recognized rather than applied twice. A handler that throws is deliberately not caught: a 500 makes Stripe retry, which is what should happen when a webhook cannot be processed yet. The two client errors have their own bare bodies rather than the shared envelope.

Base URL

https://api.signclad.com/api/v1

Authentication

None — this operation is public

Request body

application/json — A object.

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/inbound/stripe \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"