Signed webhooks
Receive durable workspace events at an authorized HTTPS destination.
Register a verified destination
In Account → API, add a webhook for an authorized workspace and select the event types your application needs. Choose a domain already verified in that workspace, or verify it through the workspace's existing domain settings first.
Verification applies to the exact hostname. A verified parent domain does not automatically authorize all its subdomains, and another workspace's verified hostname does not grant destination access.
The destination must use HTTPS and resolve to permitted public addresses. NDNCI checks the destination again when sending; it does not follow redirects or send events to loopback, private networks or cloud metadata services. If verification is removed or the domain changes workspace, delivery stops authorizing that destination.
Copy the signing secret when the endpoint is created or rotated. The secret appears once and is encrypted at rest; it is separate from the key used to call the API.
Manage destinations through the API
Use a key with webhooks:write to create, update, revoke, rotate, or replay webhook deliveries. Read-only integration monitoring uses webhooks:read. Every request selects the workspace that verified the exact destination hostname.
curl --request POST 'https://api.ndnci.com/v1/webhooks' \
--header "Authorization: Bearer $NDNCI_TOKEN" \
--header "X-Ndnci-Workspace: $NDNCI_WORKSPACE" \
--header 'Content-Type: application/json' \
--data '{"url":"https://hooks.example.org/ndnci","eventTypes":["job.completed","job.failed"],"enabled":true}'Replace the example hostname with your workspace's verified destination. Store the signing secret returned by creation or rotation; listing and delivery history never return it. Update the receiver when rotating its secret.
Use delivery history to inspect attempts and redacted failures. A manual replay preserves the event identifier, so the receiver's duplicate detection still applies. Revoke a destination when it should receive no further events.
The event feed supports authorized outbound local forwarding and durable integration polling. Treat its cursor as opaque and persist it after the receiver has processed the event successfully.
Verify the signature
Each delivery includes these headers:
Ndnci-Event-Id: <event-uuid>
Ndnci-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>Calculate HMAC-SHA256 using the signing secret and the exact bytes of <timestamp>.<raw-request-body>. Compare the signature in constant time before decoding or processing the event. Reject timestamps more than five minutes before or after the receiver's clock and deduplicate the event UUID.
Preserve the raw body before your framework's JSON parser changes whitespace or serialization. A valid signature authenticates the delivery; your handler must still verify that the event belongs to the expected workspace and process only subscribed event types.
Acknowledge before slow work
Return a successful HTTP status after durably accepting the event, then process lengthy work asynchronously. Make the handler idempotent: a retry or manual replay can deliver the same event more than once.
Webhook events are stored before delivery. Delivery has at most twelve automatic attempts. Exponential backoff starts at thirty seconds and is capped at one hour. Redirects are rejected. HTTP 400, 401, 403, 404, and 410 are permanent failures; temporary network failures and other retryable HTTP statuses are retried within that bound.
Inspect and replay delivery
The workspace's webhook controls show delivery attempts, outcomes and retry state. After correcting a receiver, replay a failed event up to the three-replay allowance. The event identifier remains stable so the receiver can detect duplicates.
Repeated destination failures produce a capped account notification instead of one email for every attempt. Keep job reads and event polling as recovery paths when a receiver is temporarily unavailable.
Develop locally
Use the outbound local forwarder for a receiver on your machine. A public tunnel is also possible when its exact hostname is verified for the workspace. Domain verification does not relax destination or SSRF checks.