How do I set up a webhook?

Requires Elite

Short answer

Open Administration → Webhooks, click “Create webhook”, and provide a name, target URL, and the subscribed events (comma-separated, e.g., asset.created). After saving, Notory shows the signing secret exactly once — save it right away. With “Send test” you send a signed ping event and immediately see whether your endpoint responds.

Prerequisites

Your receiver must accept an HTTP POST with JSON, respond with a 2xx status within 10 seconds, and should verify the signature.

Open Webhooks. Administration → Webhooks (“Send signed HTTP callbacks to external systems when events occur. The secret is shown only once.”).

Screenshot pending admin-webhooks-01 Webhook management with a list of webhooks and a 'Create webhook' button

The tenant's webhook management (from the Elite plan).
Create a webhook. Click “Create webhook” and fill in:
- Name — e.g., “Ticket System”.
- URL — the HTTPS endpoint of your system.
- Events (comma-separated) — e.g., asset.created (the available events: What events are there?).
Save the secret. After saving, you’ll see: “Signing secret – copy it now, it will not be shown again:”. Store it in your receiver’s secret store — you’ll need it for signature verification.

Screenshot pending admin-webhooks-02 One-time display of the signing secret after creating a webhook

The signing secret appears exactly once — right after creation.
Test it. Click “Send test”: Notory sends a signed ping event to your URL and immediately shows the result (status code or error).

Screenshot pending admin-webhooks-03 Test delivery of a webhook with result display (status code) and delivery log

'Send test' sends a signed ping event and logs the result.

Via the REST API: POST /api/v1/webhooks with name, URL, and event list. The secret is generated by the server — it only appears in this one response:

curl -X POST https://demo.notory.io/api/v1/webhooks \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ticket-System",
    "url": "https://tickets.acme.example/hooks/notory",
    "events": ["asset.created"]
  }'

{
  "id": "018f9f44-5e6f-7a77-b182-9c0d1e2f3a41",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "name": "Ticket-System",
  "url": "https://tickets.acme.example/hooks/notory",
  "events": ["asset.created"],
  "active": true,
  "created_at": "2026-07-08T11:02:13Z",
  "updated_at": "2026-07-08T11:02:13Z",
  "secret": "wJalrXUtnFEMI…-nur-jetzt-sichtbar"
}

Testing and managing:

curl -X POST https://demo.notory.io/api/v1/webhooks/018f9f44-5e6f-7a77-b182-9c0d1e2f3a41/test \
  -H "Authorization: Bearer inv_dein_token"

curl -H "Authorization: Bearer inv_dein_token" https://demo.notory.io/api/v1/webhooks
curl -X DELETE -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/webhooks/018f9f44-5e6f-7a77-b182-9c0d1e2f3a41

Possible errors: 403 (not an administrator, or the webhooks feature isn’t licensed — “The Webhooks module is not included in the ’…’ plan”), 404 (webhook belongs to another tenant), 422 (empty name/URL).

What happens behind the scenes?

Secret generated server-side. Notory itself creates the signing secret (32 random, URL-safe bytes) — you can’t supply your own. It’s used for the HMAC-SHA256 signature of every delivery and is never output again after the creation response. Lost the secret? Delete the webhook and create a new one (rotation).
Tenant-bound and active immediately. The webhook belongs to your tenant and is created with active: true. It only receives events belonging to its tenant — and only those listed in its event list.
No edit endpoint. Changing the URL or event list = delete the webhook and create a new one (this generates a new secret — update your receiver!).
Delivered in the background. Events are delivered best-effort after the actual action (the triggering API response doesn’t wait for your server). Every delivery is recorded with its status code or error in the delivery log.
ping for verification. The test delivery is a regular, signed event (X-Webhook-Event: ping) with {"message": "test delivery"} — ideal for developing your signature verification.