Webhooks

Troubleshooting

Start with the endpoint's delivery log in Integrations › Webhooks. Open the delivery that failed: What went wrong and the Response usually point straight at the cause. After a fix, click Redeliver to send the same payload again.

I can't see Webhooks, or the card is locked

  • Webhooks come with Professional, Premium and Enterprise plans and with free trials. On Basic, the card is shown locked with an upgrade prompt.
  • Accounts run by a white-label partner don't have webhooks.
  • Webhooks are under Manual Setup › Integrations, not in the sidebar on their own. The old Developers › Webhooks address redirects there.

The endpoint URL is rejected

Message or problemFix
The URL must use HTTPSUse an https:// address. Plain http:// isn't accepted.
"The webhook URL must point to a public internet address."Use a public domain name. localhost, IP addresses and private names such as .local, .internal or .test are rejected. To test locally, use a tunnelling tool that gives you a public HTTPS URL.
The URL is too longKeep it to 255 characters or fewer.
"You can have up to 10 webhook endpoints."Remove an endpoint you no longer use.

Deliveries fail

What you seeLikely causeFix
A 401 or 403 responseYour receiver rejected the signature or needs its own authentication.See signature mismatches below. Jodie can't send other credentials, so allow requests that pass the signature check.
A 404 or 405 responseThe path is wrong, or the route doesn't accept POST.Check the URL in Edit and that your route handles POST.
A 3xx responseJodie doesn't follow redirects.Use the final URL, for example with https:// and www as your server expects, or the trailing slash it redirects to.
A 4xx response with a validation errorYour receiver doesn't accept a field in the payload.Make it ignore fields it doesn't know. New fields and new activity types can be added over time.
A 5xx responseYour receiver threw an error.Check your server logs for the time of the delivery, fix it, then Redeliver.
A timeout, or "No response"Your endpoint took longer than 3 seconds, or couldn't be reached.Reply 200 first and do slow work in the background. Check that the host is up and publicly reachable.
A TLS or certificate errorThe certificate is expired, self-signed or missing intermediates.Use a certificate from a public authority and serve the full chain.

A delivery is retried twice before it's marked Failed. See Retries.

Signatures don't match

  • Compute the HMAC over the raw body bytes, not over parsed and re-encoded JSON. See the framework notes in Verify signatures.
  • Make sure you're using the secret for this endpoint. Each endpoint has its own.
  • Compare against the hex digest (lowercase), not Base64.
  • Check that a proxy or middleware in front of your app isn't changing the body, for example by decompressing, reformatting or changing its character encoding.

I receive the same activity twice

Retries can deliver a request your endpoint already handled, for example if it replied after the 3-second timeout. Store each Delivery-Id you process and skip repeats. A redelivery has a new Delivery-Id, so use the call_id or conversation_id in the body to recognise the same activity.

I'm not receiving some activity

  • Check what the endpoint sends: All activity, or a list of chosen types. Edit it to add the types you need.
  • Activity is sent when it finishes: when a call ends, or when a WhatsApp, email or website chat conversation closes. Open conversations aren't sent until they close.
  • Check the filters on the delivery log. They may be hiding the deliveries you're looking for.
  • The log only keeps 7 days. Older deliveries are gone, but you can still fetch calls and WhatsApp conversations with the API on plans that include it.

My receiver breaks on a new kind of activity

Endpoints on All activity automatically receive new activity types as they're added. Branch on event_type, handle the ones you know, and reply 200 to the rest. If you'd rather not receive new types, switch the endpoint to Choose activity.

Still stuck?

Email [email protected] with the endpoint URL and the Delivery ID of a failed delivery. Don't send your signing secret.

Need a hand?

Our team can help you connect Jodie to your systems.

Email [email protected]