Webhook
Webhooks allow you to receive real-time notifications when events occur on Atoa, delivered directly to an HTTP endpoint of your choice. They eliminate the need to poll the Atoa API for status updates, saving time and resources.
Event types
Subscribe to the event types relevant to your integration:
| Event type | Description | Payload reference |
|---|---|---|
PAYMENTS_STATUS | Pay by Bank and Card on File payment completed, pending, or failed | Payload |
EXPIRED_STATUS | Payment request expired before the customer completed payment | Payload |
REFUND_STATUS | Refund completed, cancelled, or failed | Payload |
POS_PAYMENT_STATUS | POS terminal payments (Pay by Bank and card) and POS-initiated refunds (voids) | Payload |
Getting started
Register your webhook endpoint
Use the Create Webhook API to register your endpoint URL and the event type you want to subscribe to.
curl --request POST \
--url https://api.atoa.me/api/webhook/merchant \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://your-server.com/webhook",
"event": "PAYMENTS_STATUS"
}'
Each event type requires a separate subscription. Use Get All Webhooks to view or Delete Webhook to remove subscriptions.
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.
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:
curl --request POST \
--url https://api.atoa.me/api/webhook/test \
--header 'Authorization: Bearer <sandbox-token>' \
--header 'Content-Type: application/json' \
--data '{
"eventType": "PAYMENTS_STATUS"
}'
Override fields like 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.
| V1 (Legacy) | V2 (Recommended) | |
|---|---|---|
| How it works | signatureHash field inside the JSON body | X-Atoa-Signature HTTP header |
| What is signed | orderId | paymentRequestId | The entire JSON request body |
| Algorithm | HMAC-SHA256 | HMAC-SHA256 |
V2 Signing
V2 signing covers the entire request body with HMAC-SHA256, making it more secure than field-level V1 signing. V2 is required for POS_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.
See the V2 Webhook Signing guide for full setup instructions and code samples in Node.js, Python, Java, Go, and PHP.
V1 Signing
V1 signing verifies authenticity using the signatureHash 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.
| Method | Description |
|---|---|
| None | No additional authentication. Rely on signature verification to validate deliveries. |
| OAuth 2.0 | Atoa obtains access tokens from your authorisation server and includes them in webhook requests. Pass clientId, clientSecret, and authUrl when creating the webhook. |
| Basic Auth | Atoa includes a username and password in the Authorization header. Pass username and password when creating the webhook. |
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 HTTP 200, 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.