POST to your endpoint when something happens on one of your pay links. Each delivery is signed with the link’s webhook_secret, so you can check that it came from Xenarch and was not replayed.
Set the endpoint
Passwebhook_url in the link params when you create the link, or set it later:
https, and Xenarch refuses URLs that resolve to private addresses. Omit event_types (or send null) to receive every event. enabled: false pauses deliveries without removing the endpoint.
The webhook_secret (whsec_ plus 64 hex characters) is returned when you create the link. To get a new one, rotate it with POST /v1/links/{link_id}/webhook/rotate-secret or xenarch links webhook rotate <link_id>. The old secret stops working, both for webhook signatures and for the usage endpoint.
Events
xenarch links webhook test <link_id> sends a test delivery to your endpoint.
Request format
25000000 is 25 USDC. Payment events can also carry reference_id (invoice number), client_reference_id, subid, and tip_micro_usdc with subtotal_micro_usdc when they apply. Subscription and charge events carry subscription_id. subscription.status_changed carries old_status and new_status.
Verify the signature
X-Xenarch-Signature has the form t=<unix_seconds>,v1=<hex>, where v1 is HMAC-SHA256, keyed with your webhook_secret, of the string <t>.<raw_body>. Reject the request when the signature does not match or when t is more than 300 seconds from your clock. Always verify the raw request body, not a re-serialized object.
webhooks.verify(payload, signatureHeader, secret, { toleranceSeconds?, throwOnFailure? }) returns a Promise<boolean>. Python: webhooks.verify(payload, signature_header, secret, *, tolerance_seconds=300, raise_on_failure=False) returns a bool. Both default to a 300 second window.
Retries
A delivery counts as delivered when your endpoint answers with a 2xx status. Otherwise Xenarch retries after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then every 6 hours, until 24 hours have passed since the first attempt. A 4xx response other than 408 or 429 stops retries for that delivery at once. After 5 failed deliveries in a row to one endpoint, Xenarch emails you. Every retry of a delivery carries the sameX-Xenarch-Delivery id. Use it to ignore duplicates. List recent attempts with xenarch links webhook deliveries <link_id> and queue one again with xenarch links webhook retry <link_id> <delivery_id>.
Agent webhooks, configured for an agent rather than a pay link, use the same signature scheme and the same verify call.