Skip to main content
Danube webhooks send HTTPS POST requests to your server when events happen on your account. Use them to trigger downstream actions, log activity, or alert your team — without polling.

Quick Start

1

Create a webhook

Go to Dashboard > Webhooks, click Add Webhook, enter your HTTPS endpoint URL, and select the events you want to receive.You can also create one via the API:
2

Save your signing secret

After creation you’ll see a signing secret (starts with whsec_). Copy it immediately — it won’t be shown again. You’ll use this to verify that incoming requests actually came from Danube.
3

Build your endpoint

Your server needs to do three things:
  1. Read the raw request body and parse the signature header
  2. Verify the HMAC signature (which includes a timestamp for replay protection)
  3. Return a 2xx status code within 10 seconds
Here’s a minimal example:
4

Test it

Trigger an event (e.g. execute a tool) and check the delivery status in Dashboard > Webhooks. Expand your webhook to see recent deliveries, including HTTP status codes and response bodies.

Event Types

Payload Format

Every delivery uses this envelope:

Signature Verification

Every delivery includes a signed X-Danube-Signature header with a timestamp for replay protection. Always verify it before processing.

How it works

The signature header has the format:
  1. Danube computes HMAC-SHA256("{timestamp}.{raw_body}", your_secret) and sends the result along with the timestamp
  2. Your server reconstructs the same signed content ({timestamp}.{raw_body}) and computes the HMAC using the secret you saved at creation
  3. Compare the two digests using a constant-time comparison to prevent timing attacks
  4. Reject deliveries where the timestamp is too old (e.g. more than 5 minutes) to prevent replay attacks

Request Headers

Retries and Failures

If your endpoint doesn’t return a 2xx or the request times out, Danube retries with exponential backoff: After 3 failed attempts the delivery is marked as failed. You can inspect delivery history (status codes, response bodies, attempt counts) in the dashboard.

Best Practices

Respond fast

Return 200 immediately, then process the event asynchronously. The delivery times out after 10 seconds.

Verify signatures

Always validate X-Danube-Signature before trusting the payload. Never skip this in production.

Check the timestamp

Reject signatures where t is more than 5 minutes old to prevent replay attacks.

Handle duplicates

Use the X-Danube-Delivery UUID to deduplicate. Network retries may deliver the same event more than once.

Use HTTPS

Webhook URLs must use https://. Danube will not deliver to plain HTTP or internal/private endpoints.

API Reference

List Webhooks

Get all your registered webhooks

Create Webhook

Register a new webhook endpoint

Update Webhook

Change URL, events, or active status

View Deliveries

Inspect delivery history and debug failures