Delivery and retries
Zeam delivers each event byPOST and expects a 2xx response. A non-2xx
response, a timeout, or a connection error is treated as a failure and retried
with backoff. After the maximum number of attempts the delivery is
dead-lettered and no longer retried.
Current defaults (configurable by Zeam):
- Up to 3 attempts per delivery, then dead-letter.
- 15-second request timeout per attempt.
- Payloads larger than 128 KiB are not delivered.
Common scenarios
The endpoint cannot be reached
The endpoint cannot be reached
Confirm the URL is public, correct, and reachable from the internet, and
that DNS resolves. Localhost and private addresses are not reachable by
Zeam. After fixing, send a test event from the portal.
TLS or certificate errors
TLS or certificate errors
Use a valid, non-expired certificate from a trusted CA on a standard HTTPS
port. Self-signed certificates are rejected in production.
The endpoint returns a non-2xx status
The endpoint returns a non-2xx status
Return a
2xx as soon as you have stored the event, then process it on a
background worker. Slow processing before acknowledging risks a timeout and
a retry.Events are duplicated
Events are duplicated
Retries can deliver the same event more than once. De-duplicate on the
X-Webhook-Id header and return 2xx for an event you have already
processed.Events arrive later than expected
Events arrive later than expected
Delivery is asynchronous and retried with backoff, so events can lag and can
arrive out of business-process order. Do not depend on timing or order;
reconcile with the Transactions API.
A transaction changed state but no webhook arrived
A transaction changed state but no webhook arrived
Check that you have an active registration for that event type (there is
one per association and event type, and disabling is permanent). The
delivery may also have been dead-lettered after repeated failures. Poll
GET /v1/transactions/{transactionId} to
recover the current state.The payload cannot be parsed
The payload cannot be parsed
Read the raw request body and parse it as JSON (
Content-Type: application/json). If you verify the signature, do so over the raw bytes
before parsing.Signature validation fails
Signature validation fails
Recompute the HMAC-SHA256 over the exact raw body using your association id
as the key, and compare against the value after the
sha256= prefix. A
common cause is verifying against a re-serialised body. See
Security.Sandbox and production URLs are confused
Sandbox and production URLs are confused
Registrations belong to a single environment. Confirm you registered the
endpoint in the same environment your traffic runs in, and that each
environment points at the correct URL.