Webhooks

Subscribe

POST
/v1/workspaces/{workspace_id}/webhooks

Sends the events chosen to an https URL. The answer holds the signing secret, shown this once. Each delivery carries X-Signature: v1=<hex>, HMAC-SHA256 of <X-Signature-Timestamp>.<body> under the secret: check it, reject anything older than 5 minutes, and dedupe on the event ID. Send an Idempotency-Key: the same key returns the same answer for 24 hours.

Authorization

bearer
headerAuthorizationBearer <token>

An access token from /v1/auth/token, or a personal token: opaque, beginning s2a_.

Path Parameters

workspace_id*string

wsp_…, from GET /v1/me

Lengthlength <= 40

Header Parameters

idempotency-key*string

A UUID of your own (ADR 0071 §5)

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Request Body

application/json
  1. body
url*string
Lengthlength <= 2000
events*array<>
Items1 <= items
document_type_ids?array<string>
description?string
Lengthlength <= 200

Response Body

Subscribed

application/json
  1. response

Subscribed

webhook*
secret*string

whsec_…, shown this once

curl -X POST 'https://api.sign2approve.com/v1/workspaces/string/webhooks' \  -H 'idempotency-key: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "url": "string",  "events": [    "envelope.created"  ]}'
{  "webhook": {    "id": "whk_01a16d3fd3507be78e41c4540aa20a3c",    "url": "https://hooks.example.com/esign",    "events": [      "envelope.completed",      "timeoff.approved"    ],    "status": "active",    "scopes": [      "documents:envelopes:read"    ],    "created_at": "2026-10-24T09:30:00Z"  },  "secret": "whsec_…"}