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 or Session

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 or Session

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 or Session

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 or Session

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 or Session

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 or Session

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": "01j9k3p2s5b3c4d5e6f7g8h9jk",
  "url": "https://app.example.com/webhooks/signclad",
  "description": "Production receiver",
  "event_types": [
    "document_completed",
    "document_declined",
    "document_error"
  ],
  "events": [
    "document_completed",
    "document_declined",
    "document_error"
  ],
  "api_application_id": null,
  "include_test_mode": false,
  "active": true,
  "status": "active",
  "compatibility": false,
  "secret_last_rotated_at": "2026-08-20T14:03:22+00:00",
  "created_at": "2026-04-02T08:15:00+00:00",
  "updated_at": "2026-09-09T17:44:10+00:00",
  "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:58+00:00",
    "last_failure_at": "2026-09-08T22:11:04+00:00",
    "last_failure_reason": "502 Bad Gateway",
    "failing_since": null,
    "next_probe_at": null,
    "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 or Session

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 or Session

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 or Session

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 or Session

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 (failures for 15 minutes without a success, or over 25% failures in an hour while the latest attempt is still failing) → failing (25 consecutive failures, or 100% over 24 hours) → disabled (5 days of continuous failure). An endpoint returns to healthy once the latest attempt succeeds and the last hour is back under 25% failures. 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 or Session

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 or Session

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": "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 or Session

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": "MDFqOWszcDJzNW43cThyMXQydjN3NHg1",
  "has_more": true,
  "data": [
    {
      "id": "01j9k3p2s5n7q8r1t2v3w4x5",
      "webhook_endpoint_id": "01j9k3p2s5b3c4d5e6f7g8h9jk",
      "event_id": "evt_01j9k3p2s5n7q8r1t2v3w4x5",
      "event_type": "document_completed",
      "document_id": "8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60",
      "status": "failed",
      "next_retry_at": "2026-09-09T18:00:00+00:00",
      "delivered_at": null,
      "created_at": "2026-09-09T17:44:15+00:00",
      "request_headers": {
        "X-Signclad-Event": "document_completed",
        "X-Signclad-Event-Id": "evt_01j9k3p2s5n7q8r1t2v3w4x5",
        "X-Signclad-Delivery": "01j9k3p2s5n7q8r1t2v3w4x5",
        "X-Signclad-Attempt": "2",
        "X-Signclad-Signature": "t=1789050255,v1=6f4a9c2e8b1d3f5a7c9e0b2d4f6a8c1e3b5d7f9a0c2e4b6d8f0a2c4e6b8d0f2a"
      },
      "attempts": [
        {
          "attempt": 1,
          "attempted_at": "2026-09-09T17:44:15+00:00",
          "status_code": 502,
          "latency_ms": 10021,
          "response_excerpt": "<html>502 Bad Gateway</html>"
        },
        {
          "attempt": 2,
          "attempted_at": "2026-09-09T17:45:15+00:00",
          "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 or Session

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, and what its data.object carries, along with the signature scheme and the retry schedule. Generated from the same table the delivery pipeline validates subscriptions against, so the catalog cannot claim an event that is not deliverable and cannot omit one that is. Events a deployment has turned off are absent from the catalog, so subscribe from this list rather than from a hard-coded one.

Base URL

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

Authentication

API key or OAuth 2.1 access token or Session

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": false
    }
  ],
  "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 or Session

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 or Session

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 or Session

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 or Session

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 or Session

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 or Session

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"