Skip to main content
POST
Register a webhook endpoint

Authorizations

Authorization
string
header
required

A Surfais API key — an organisation key or a partner key. Issued by Surfais; shown once. Rotate by creating a new key, then revoking the old one.

Headers

Idempotency-Key
string

Optional. 1–255 characters, unique per intended write. Same key + same request → the stored response is replayed with Idempotent-Replayed: true; same key + different request → 409 idempotency_key_reuse; still running → 409 idempotency_key_in_flight. Outside that range → 400 validation_error (invalid_header).

Required string length: 1 - 255

Body

application/json
url
string
required

https URL of your receiver. Must resolve to a public address; no embedded credentials.

Required string length: 1 - 2048
description
string | null

Free text for your own bookkeeping.

Maximum string length: 200

Response

The endpoint, with its signing secret (once).

data
object
required