Skip to main content
Create and manage webhook endpoints under Business profile → Developers → Webhooks.

Verification key

Fetch Anyway’s public Ed25519 key and cache it:
publicKey is the prefixed raw-key representation, while keys is the equivalent JWKS representation. The delivery envelope follows Standard Webhooks and uses an asymmetric Ed25519 (v1a) signature. Refresh the cached key if verification begins failing after a key rotation.

Events

Current events are: An empty endpoint event selection subscribes to all supported events. Fulfill only after a verified order.paid. A period-end cancellation is reported through subscription.updated; use cancelAtPeriodEnd and currentPeriodEnd to represent the scheduled state before subscription.ended.

Delivery headers and signed content

The signed message is the exact byte sequence:
Verify against the raw request body before JSON parsing. Reject stale timestamps and unknown signatures.

Verify Ed25519 signatures

Payload

The signed envelope contains type, RFC 3339 timestamp, apiVersion, endpoint identity, and either data.order or data.subscription, according to the event type. Important order fields include: For a payment link opened with merchant_reference=PUR_456&user_id=USR_123&source=web, an order event contains the same values:
The webhook signature covers the exact raw body, including merchantMetadata. Signature verification proves that Anyway delivered the payload; it does not make the original buyer-visible query values suitable for authorization. Never authorize access solely from merchantMetadata, a buyer note, email, or URL parameter. Compare the order, amount, currency, product, and reference with your own server-side record.

Subscription payload

Subscription events use data.subscription. Important fields include:
merchantReference and merchantMetadata belong to order payloads. They are not fields of data.subscription; use subscriptionId to query related orders when you need the initial checkout context.

Delivery behavior

  • Return a 2xx quickly after durable enqueueing.
  • Each attempt has a 10-second timeout.
  • Transport failures, 408, 429, and 5xx responses are retried.
  • 3xx responses and permanent 4xx responses other than 408 and 429 are not retried.
  • Delivery allows up to 12 attempts with exponential backoff capped at one hour.
  • Retry-After is honored for 429 and 503, up to the one-hour cap.
  • Delivery is at least once and events can arrive out of order.
Use webhook-id as the delivery idempotency key. Do not let a late pending event regress a locally paid order or let an older subscription update overwrite newer lifecycle state.
Do not log webhook signatures, API keys, full payment details, identity documents, payout-account information, or unredacted customer metadata.