Event types
Subscribe to the event types relevant to your integration:Multiple endpoints per event type
You can register up to 3 endpoints per event type. When an event fires, Atoa delivers the webhook to all registered endpoints for that event simultaneously — each endpoint receives its own independent delivery with its own retry tracking. This lets different systems subscribe to the same event independently without coupling them together. For example:
All three endpoints above receive
PAYMENTS_STATUS webhooks independently. A failure at one endpoint does not affect delivery to the others.
The limit is 3 endpoints per event type. Attempting to register a fourth endpoint for an event type that already has 3 returns a
400 error. Use List endpoints to review your current registrations. Multiple endpoints per event type is a v2-only feature — v1 supports one endpoint per event type.API versions
Atoa provides two webhook API versions. Use v2 for all new integrations.
v1 remains supported for existing integrations. For new implementations, use the v2 API, which lets you subscribe to multiple event types per endpoint and manage authentication after creation.
Getting started
1
Register your webhook endpoint
Use the Create Endpoint (v2) API to register your endpoint URL and subscribe to one or more event types in a single call.Use List Endpoints to view, Update Endpoint to modify, or Delete Endpoint to remove subscriptions.
2
Handle incoming payloads
Return HTTP
200 on success — any other response triggers retries. Each event type has a different payload structure — see the Event types table for payload references.3
Verify the signature
Every webhook delivery is signed so you can verify it genuinely came from Atoa. See Signature verification below for the two available methods.
Testing your webhook
Send a test webhook to your sandbox URL without creating a real payment. The body and signature match a production event, so you can verify your integration end-to-end before going live. Use the Trigger test webhook event endpoint:orderId, amount, paymentMethod, and status to simulate specific scenarios. See the Trigger test webhook event reference for all available fields and per-event rules.
Test triggers are sandbox-only — production keys are rejected. You must have an active subscription for the event type before the trigger will deliver.
Signature verification
Atoa supports two methods for verifying webhook authenticity. We recommend V2 signing for all new integrations.V2 Signing
V2 signing covers the entire request body with HMAC-SHA256, making it more secure than field-level V1 signing. V2 is required forPOS_PAYMENT_STATUS webhooks.
- Generate a signing secret from the Atoa Dashboard under Settings → Webhooks.
- For every incoming webhook, compute
HMAC-SHA256(signingSecret, rawRequestBody)and compare the hex digest against theX-Atoa-Signatureheader value (after stripping thev1=prefix). - Use a timing-safe comparison function to prevent timing attacks.
V1 Signing
V1 signing verifies authenticity using thesignatureHash field included in the webhook body. It signs only the orderId and paymentRequestId (or refundId for refund webhooks).
See the V1 Webhook Signing guide for full verification steps and code samples.
If you enable V2 signing, the
signatureHash and signature fields are removed from the webhook body and an eventType field is added instead. V1 and V2 cannot be used simultaneously for the same merchant.Endpoint authentication
Optionally configure authentication so Atoa includes credentials in every delivery, in addition to signature verification.Signature verification cryptographically proves requests come from Atoa. For maximum security, combine it with OAuth or Basic Authentication.
Retry mechanism
When a webhook response is anything other than HTTP200, it is considered a failure. Our system retries using an exponential back-off strategy. If the webhook continues to fail over 24 hours, Atoa stops the retry attempts and sends an email notification to the business owner with the failing webhook URL.