Operational Notes

Use these checks when running or recovering a webhook receiver.

Monitoring deliveries

Use the webhook delivery log for the canonical filters, response fields, and examples. Alert on failed deliveries, unexpectedly old pending events, and your own inbox processing failures. A delivered status means HTTP intake succeeded, not that your business work finished.

Keep event IDs, purchase IDs, and processing outcomes in your own diagnostic records. The public log contains delivery metadata; it does not return the raw payload.

Response truncation

TradeOn stores at most the first 500 characters of the response body for support diagnostics. Keep errors concise: a short JSON response is more useful than an HTML error page. This diagnostic response body is not part of the public delivery-log response.

Rotating the webhook URL

Update the URL in the merchant cabinet at merchant.tradeon.market, under Settings → Webhook. Future attempts, including retries of existing events, use current settings. Requests already in flight may still reach the previous endpoint; keep it accepting valid requests while those attempts finish.

The destination must use HTTPS and resolve to a public address. Validation also runs at delivery time: a destination that later resolves to a private range is rejected as a terminal failure. Review failed deliveries after moving the endpoint and use manual replay if necessary.

Webhook secret hygiene

Store the secret in a secrets manager and never log it. It is shown only once when generated. Rotation takes effect immediately for future attempts; signatures on requests already in flight can still use the preceding secret. Coordinate your receiver’s short transition window as described in secret rotation. If the secret leaked, revoke it promptly and inspect delivery failures after the switch.

IP whitelist

Verify the signature on every request. Do not use an IP address as a substitute for signature verification. If your receiver requires a network allow-list, confirm the current supported egress arrangement with TradeOn before restricting ingress; this documentation does not promise fixed sender IP addresses.

Maintenance windows

Already-stored events remain subject to the finite delivery retry policy. An outage can delay attempts or exhaust their retries. Configure an endpoint before relying on event delivery: changes that occur without a webhook URL are not automatically replayed later.

Do not assume every business transition is captured during an event-creation or storage failure, or that there is a guaranteed catch-up backlog after maintenance. Pair webhooks with regular purchase and balance reconciliation. Increase reconciliation after an outage, and use the delivery log to distinguish a stored failed delivery from an unobserved state transition.