Webhooks

Troubleshooting

Find your symptom in the tables below. Each row gives the likely cause and the fix.

On this page

No events arrive
The signature does not match
The same event arrives many times
Events arrive in the wrong order
A field or a value is not what you expect
Ask Merxian for help

No events arrive#

Cause	Fix
The endpoint is in the other environment. Sandbox events go only to sandbox endpoints, and live events only to live endpoints.	Add the endpoint in the environment of your API key.
The endpoint does not subscribe to the event type.	Add the event type to the endpoint in the dashboard. Customer events are opt-in.
The live URL uses `http`, or it resolves to a private, loopback, or local address.	Use an `https` URL on a public host.
The URL redirects, for example from `http` to `https` or to add a trailing slash.	Enter the final URL. Merxian does not follow redirects.
A firewall or a proxy blocks the request, or needs a login.	Allow `POST` requests to the webhook route without a login. The signature authenticates the request.
Your endpoint returned `4xx` for an earlier attempt.	Merxian does not retry a `4xx`. Fix the handler. Recover the state from the API. See Delivery and retries.

The signature does not match#

Cause	Fix
Your framework parsed the JSON and you signed the serialized result.	Verify the raw body bytes, before any parsing. See Verify signatures.
A middleware changed the body, for example to trim whitespace or to change the encoding.	Read the body as raw bytes on the webhook route.
You use the secret of the other environment or of another endpoint.	Use the secret of the endpoint that receives the event.
You used the secret as the key without decoding it.	Remove `whsec_` and decode the rest from base64. Use the decoded bytes as the key.
You rotated the secret and deployed only part of your servers.	Deploy the new secret to every server.
The clock of your server is wrong, so the timestamp check fails.	Sync the clock with NTP. Keep a tolerance of about 5 minutes.
You compare the signature in upper-case hex.	Merxian sends lower-case hex. Compare the bytes, or compare lower-case strings.

The same event arrives many times#

Cause	Fix
Your endpoint answers after 10 seconds.	Return `200` first, then process the event.
Your endpoint returns `5xx` or `429`.	Return `2xx` when the event is stored. Handle your own failures in your queue.
Normal at-least-once delivery.	Process each event `id` once. See Process events.

Events arrive in the wrong order#

Merxian does not guarantee an order. Read the current state from the API, or accept only events that move your record forward. See Do not depend on order.

A field or a value is not what you expect#

Cause	Fix
Webhook payloads use snake_case, and the API uses camelCase.	Use the field names of the event pages.
Some state values differ between the API and webhooks, for example `cancelled` and `canceled`.	See State values in payloads.
The payload shows an older state.	The payload is a snapshot. Read the resource from the API for the current state.
An event that you expect does not arrive, for example `customer.updated`.	Check that the endpoint subscribes to it in the dashboard.

Ask Merxian for help#

Give the Merxian-Delivery-Id and the Merxian-Event-Id of the request, the time that you received it, and your response status. Do not send your signing secret.