Create webhook

Creates a webhook subscription for the calling website: whenever an event matching one of topics happens, commons-api signs and POSTs (or PUT/PATCHes) a payload to url.

The signing secret is returned exactly once, in this response, and never again. Store it immediately — no endpoint ever exposes it again, including GET on this same webhook. If you lose it, the only recovery is deleting and recreating the endpoint (secret rotation without deletion isn't available yet).

Read the Webhooks usage guide doc in this folder before integrating — it covers signature verification, the retry/failure model, and the full payload envelope shape, none of which is obvious from this endpoint's shape alone.

Recommended flow before going live: create the endpoint, then call POST /v4/webhooks/{id}/test with a topic of your choice to confirm your receiver accepts the signature and shape correctly — this sends one real HTTP call to your URL synchronously and returns the raw response, without entering the retry/delivery-log system at all.

curl --location '/v4/webhooks' \ --header 'Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6Im1haW4ta2V5IiwidHlwIjoiSldUIn0...' \ --header 'Content-Type: application/json' \ --data '{ "description": "string", "scope": "website", "topics": [ "contact.created" ], "filter": {}, "url": "string", "method": "post", "headers": [ { "key": "string", "value": "string" } ], "auth": { "type": "bearer", "token": "string" }, "bodyFormat": "json", "body": "string", "batch": { "max": 0, "waitMs": 0 }, "rateLimitPerSec": 0, "maxConcurrency": 0 }'

{"id": "7b5bea64-cd4f-4d97-a4ea-cef565d7c0c3", "scope": "website", "websiteId": "3f2a9c4e-8b1d-4a6f-9c2e-7d5f1a8b3e6c", "description": "Sync unsubscribes to the shop", "topics": ["contact.unsubscribed"], "filter": null, "status": "enabled", "payloadVersion": "amos", "url": "https://shop.example.cz/api/webhooks/incomaker", "method": "post", "headers": [], "authType": null, "bodyFormat": "json", "body": null, "batchMax": 1, "batchWaitMs": 0, "rateLimitPerSec": null, "maxConcurrency": 4, "createdAt": "2026-08-25T23:23:48.000Z", "updatedAt": "2026-08-25T23:23:48.000Z", "links": {"self": "/v4/webhooks/7b5bea64-cd4f-4d97-a4ea-cef565d7c0c3", "deliveries": "/v4/webhooks/7b5bea64-cd4f-4d97-a4ea-cef565d7c0c3/deliveries"}, "secret": "whsec_QRmYErDeCzTFLF14ZbkjuW8pOF2MBfeb9InJuuGSTBU="}

Request

Responses