Troubleshooting
Webhook not arriving
What to check when events do not reach your endpoint.
Each symptom below follows the same shape: what you see, the cause and what to do.
Start with a test
Section titled “Start with a test”Send a destination.test event to the destination and look at the result. In the panel, open the destination’s deliveries: each attempt keeps the status and the first 1024 bytes of your response.
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/test \ -H "Authorization: Bearer $MESSAJO_API_KEY"import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY });
await messajo.destinations.test(destinationId);The test goes only to that destination, in a single attempt, even if it is paused.
Nothing arrives
Section titled “Nothing arrives”- Destination paused, by you or by the automatic pause (
auto_paused). Every new event becomes afaileddelivery withdestination_paused. Resume the destination and resend the failures (below). - Filter does not match. Check
event_types(*,message.*or the exact type) and whether the destination belongs to a connection or is global (connection_id: null). A connection destination only receives that connection’s events; organization events, such asorg.standing_changed, only reach global destinations. See Filters. - Connection not Active. Check its status in the panel. If it is Restricted, Disabled or Disconnected, see Number restricted or banned.
- URL refused at creation:
400destination_url_not_allowed. Private networks,httpand invalid hosts are not accepted. Use a publichttpsURL;details[].messagegives the reason.
It arrives, but shows as a failure
Section titled “It arrives, but shows as a failure”Success is a 2xx response within 10 seconds, in total. Anything else counts as a failure: another status, timeout, network error or blocked address. A redirect (3xx) is not followed and counts as a failure.
Answer 2xx fast and process later, in your own queue. Heavy work inside the request blows the time limit.
The signature does not match
Section titled “The signature does not match”The five causes from Common mistakes:
- Re-serialized JSON: sign the raw body, never
JSON.stringify(req.body). - Clock outside the 5 minute tolerance: sync the server (NTP).
- Space or line break at the end of the secret (common in
.env). - Secret without the prefix: the key is the whole secret, with
whsec_. - Body read with another charset: read the bytes as UTF-8.
During secret rotation the header carries two v1 values, one per active secret. One match is enough.
Repeated or out-of-order events
Section titled “Repeated or out-of-order events”Delivery is at least once. Deduplicate by Messajo-Event-Id (the same as the envelope id) and, inside a conversation, order by sequence. See Order and duplicates.
How many times it retries
Section titled “How many times it retries”1 immediate attempt plus 14 more, over a little more than 23 hours: waits of 10 s, 30 s, 1 min, 2 min, 5 min, 10 min, 20 min, 40 min, 1 h, 2 h, 3 h, 4 h, 6 h and 6 h. Each wait varies by ±10% and no attempt goes out more than 24 hours after the delivery was created. The full table is in Retries and failures.
The destination paused on its own
Section titled “The destination paused on its own”A destination is paused when it reaches 10 consecutive failures and has been failing for at least 24 hours. Any 2xx resets the count. When it pauses, owners and admins get an email. Details in Automatic pause.
Recover what was missed
Section titled “Recover what was missed”Fix the endpoint, resume the destination and resend the failures: Resend failures in the panel, or the API with since (up to 1000 per call; with has_more: true, call again).
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/redeliver-failed \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "since": "2026-11-17T00:00:00Z" }'const { queued, has_more } = await messajo.destinations.redeliverFailed( destinationId, { since: "2026-11-17T00:00:00Z" });The response is { queued, has_more }. Deliveries and events are kept for 30 days. See Failure list and redelivery.
Developing without a public URL
Section titled “Developing without a public URL”If your process has no public URL (script, desktop, local environment), see the WebSocket destination.