Generic Webhook Channel Setup

Use this channel when an external system needs to send messages to Dawn over HTTP without a native channel integration. Dawn can only use the payloads you send and the webhook conversation it has already stored.

Before you start

• A Dawn workspace and at least one agent profile.
• An external system that can send HTTP requests to Dawn.
• An origin strategy for those requests: either explicit allowed origins or * when you intentionally want unrestricted access.
• If you want asynchronous delivery of assistant replies, a callback endpoint Dawn can reach.

1) Create the Webhook binding

1. Open Channels → Add channel → Generic Webhook.
2. Optionally set a Display name and your own Public key. If you leave the key empty, Dawn generates one.
3. Turn the binding on with Enable this channel.
4. Choose whether to require HMAC signatures. This is strongly recommended for production use.
5. Set the optional Callback URL if you want Dawn to push assistant replies to another system after processing.
6. Set Allowed origins, one per line. This is required while the binding is enabled.
7. Create the binding and assign it to an agent.
8. Open Webhook Setup from the channel list to copy the endpoint URL, public key, and sample requests.

2) Send a webhook message

The main endpoint is POST /api/v1/channels/webhook/messages.

{
  "publicKey": "wh_example",
  "conversationExternalId": "client:wh_example:session-1",
  "text": "Deployment completed for service api",
  "userId": "ci-bot",
  "userName": "CI Bot",
  "idempotencyKey": "deploy-001"
}

• publicKey is required.
• Send either text or uploaded attachmentIds.
• attachmentUrls are not supported.
• Use idempotencyKey when the sender may retry the same event.

3) Signatures and allowed origins

When signature enforcement is enabled, Dawn expects:

• X-Dawn-Timestamp
• X-Dawn-Signature

The signature format is hex(hmac_sha256(secret, "{timestamp}.{rawBody}")).

timestamp=$(date +%s)
body='{"publicKey":"wh_example","text":"Hello Dawn"}'
signature=$(printf "%s.%s" "$timestamp" "$body" | openssl dgst -sha256 -hmac "$DAWN_WEBHOOK_SECRET" -binary | xxd -p -c 256)

curl -X POST "https://api.dawnhq.ai/api/v1/channels/webhook/messages" \
  -H "Content-Type: application/json" \
  -H "Origin: https://sender.example.com" \
  -H "X-Dawn-Timestamp: $timestamp" \
  -H "X-Dawn-Signature: $signature" \
  -d "$body"

Allowed origins are enforced for webhook traffic. If the allowlist is not *, your request must include an Origin header that matches one of the configured origins. This matters even for curl and server-to-server tests.

4) Attachments, history, and callbacks

• Upload files first with POST /api/v1/channels/webhook/attachments, then reference the returned attachmentId in a normal message request.
• Read stored conversation history with GET /api/v1/channels/webhook/messages?publicKey=...&conversationExternalId=....
• If signatures are enabled, sign history reads too. The history request uses an empty body.
• If Callback URL is configured and Dawn produces a reply, Dawn can push that reply to the callback target after processing.

Validation checklist

• Use the cURL sample from Webhook Setup and confirm Dawn accepts the request.
• The test event creates a conversation in Dawn with the expected external conversation ID.
• If signatures are enabled, an invalid signature is rejected and a valid one succeeds.
• If a callback URL is configured, one assistant reply reaches that callback endpoint.

Troubleshooting

• 401 invalid signature: the signing secret does not match, the signature format is wrong, or the timestamp is outside the allowed skew window.
• 400 request origin is not allowed: the request is missing an Origin header or the value does not match the configured allowlist.
• Duplicate events: use idempotencyKey so Dawn can safely deduplicate retries.
• No callback delivery: confirm the callback URL is configured, reachable from Dawn, and that Dawn actually produced an assistant reply.
• No conversation appears: check that the binding is enabled, assigned to an agent, and that the payload includes a valid publicKey plus either text or attachmentIds.

Review generic webhook binding security settings and suggest hardening changes.

List recent webhook signature validation failures with reasons.