Skip to content

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.

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.

Janela do terminal
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/test \
-H "Authorization: Bearer $MESSAJO_API_KEY"

The test goes only to that destination, in a single attempt, even if it is paused.

  • Destination paused, by you or by the automatic pause (auto_paused). Every new event becomes a failed delivery with destination_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 as org.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: 400 destination_url_not_allowed. Private networks, http and invalid hosts are not accepted. Use a public https URL; details[].message gives the reason.

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 five causes from Common mistakes:

  1. Re-serialized JSON: sign the raw body, never JSON.stringify(req.body).
  2. Clock outside the 5 minute tolerance: sync the server (NTP).
  3. Space or line break at the end of the secret (common in .env).
  4. Secret without the prefix: the key is the whole secret, with whsec_.
  5. 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.

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.

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.

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.

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).

Janela do terminal
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" }'

The response is { queued, has_more }. Deliveries and events are kept for 30 days. See Failure list and redelivery.

If your process has no public URL (script, desktop, local environment), see the WebSocket destination.