Webhooks

[Gurwinder7735]

[api] {"timestamp":"2026-06-03T13:39:06.094Z","level":"error","context":"WebhookService","message":"Webhook delivery failed for 2dfdbbc5-9187-48d6-b9f8-5691cf5cc222","webhookId":"2dfdbbc5-9187-48d6-b9f8-5691cf5cc222","attempt":3,"deliveryId":"dlv_bb2c5c55-1b76-40fd-be1c-c1afe9059090","action":"webhook_delivery_failed","trace":"Error: HTTP 401: Unauthorized"}

Can anyone tell how to use webhooks getting this ?

[rmyndharis]

Hi @Gurwinder7735 — that HTTP 401: Unauthorized in the webhook delivery log is coming from your webhook receiver, not from OpenWA. Let me explain what's happening.

How OpenWA signs webhook deliveries

When you set a secret on your webhook (in the dashboard or via the API), OpenWA signs every delivery with HMAC-SHA256 and sends the signature in the X-OpenWA-Signature header, formatted as:

X-OpenWA-Signature: sha256=<hex digest of HMAC-SHA256(secret, rawRequestBody)>

If your receiver validates that header against its own computed HMAC and the two don't match, the receiver returns 401 — and that's exactly what OpenWA logs as HTTP 401: Unauthorized after attempt 3.

Common causes

1. Secret mismatch. The secret your receiver is using to verify doesn't match the one OpenWA has on file. Double-check both sides character-for-character (no trailing whitespace, no quotes).
2. Receiver not reading the raw body. HMAC must be computed over the exact bytes OpenWA sent — i.e. the raw request body, not JSON.stringify(parsedBody). If your framework parses JSON before you compute the HMAC, the bytes differ and verification fails. Most frameworks let you access the raw body (Express: req.rawBody with a verify hook; Next.js: read the stream before parsing).
3. Receiver expects a different header name. OpenWA uses X-OpenWA-Signature. If your receiver checks X-Hub-Signature-256 or X-Signature, it'll see no signature and reject.
4. No secret on the webhook, but the receiver demands one. If you didn't set a secret in OpenWA, no signature header is sent at all — your receiver will reject as unauthorized.

How to debug

• Check the webhook config in the OpenWA dashboard: is a secret set?
• On the receiver side, log the incoming X-OpenWA-Signature header and the body your code is hashing. Compare.
• If you want to disable verification temporarily to isolate the issue, set the secret to empty on both sides.

The docs at /api/docs (search for "webhook") have the full signing contract. If you can share what stack your receiver is built on, I can give you a concrete verification snippet. 🙂