Webhooks
Subscribe
POST
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.
bearerheader
AuthorizationBearer <token>An access token from /v1/auth/token, or a personal token: opaque, beginning s2a_.
workspace_id*stringwsp_…, from GET /v1/me
Length
length <= 40idempotency-key*stringA 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)$Format
uuidapplication/json- body
url*stringLength
length <= 2000events*array<>Items
1 <= itemsdocument_type_ids?array<string>description?stringLength
length <= 200Subscribed
application/json- response
Subscribed
webhook*secret*stringwhsec_…, 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_…"}