Webhooks

Notifications about invoices, deposits and withdrawals sent to your HTTPS endpoint as flat JSON (camelCase, schema version 2).

Setup

Open the project settings.
Go to the «Integrations» section.
Enter the notification URL and save.
The system creates a secret for verifying requests.

How it works

On a significant change of an invoice, deposit or withdrawal, the system saves the object state with a new revision and creates an event.
Atomic Pay sends a POST request with a JSON body and a signature in the headers to your URL.
Your server verifies the signature against the raw body, stores the event and returns a successful response.
If the server does not respond or returns 5xx, 408 or 429, delivery is retried.
Detect duplicates by eventUuid. For several events of one entity, process the latest revision.

Event types

type	eventType
`invoice`	`invoice.created`, `invoice.updated`, `invoice.partially_paid`, `invoice.completed`, `invoice.overpaid`, `invoice.expired`, `invoice.cancelled`
`deposit`	`deposit.detected`, `deposit.confirmed`, `deposit.reorged`, `deposit.failed`
`payout`	`payout.requested`, `payout.queued`, `payout.broadcasted`, `payout.confirmed`, `payout.failed`, `payout.cancelled`

Common fields

Field	Description
`schemaVersion`	Webhook schema version.
`type`	Entity type: `invoice`, `deposit` or `payout`.
`eventType`	The event that triggered the webhook.
`eventUuid`	Unique event ID. Stays the same on redelivery.
`revision`	Entity state version. Increases on changes.
`uuid`	Entity or deposit ID.
`projectUuid`	Project UUID.
`status`	Current entity state.
`isFinal`	Whether the state is final.
`occurredAt`	Event time, UTC ISO 8601.
`createdAt`	Entity creation time, UTC ISO 8601.
`updatedAt`	Last change time, UTC ISO 8601.

uuid identifies the entity or deposit, not the event itself. Use eventUuid to identify the event.

In webhooks, merchantAmount is calculated before the network fee is deducted. In the HTTP API the field includes the final fees and may be null until they are calculated — do not compare the two directly.

Example: deposit.confirmed

{
  "schemaVersion": 2,
  "type": "deposit",
  "eventType": "deposit.confirmed",
  "eventUuid": "9214fc7c-fc28-4397-b661-4dd873f811f9",
  "revision": 2,
  "uuid": "84e89df6-2801-46a8-a49f-e0b37a9775bd",
  "projectUuid": "73e68013-32f0-4248-95ac-46aed61e59b0",
  "depositSource": "project_wallet",
  "status": "confirmed",
  "isFinal": true,
  "depositResult": "accepted",
  "walletAddressUuid": "7d8bf964-9685-4065-ad77-9fc239a2c59f",
  "staticWalletUuid": null,
  "orderId": null,
  "fiatAmount": "1.5",
  "fiatCurrency": "USD",
  "fiatRate": "0.1",
  "address": "DA6Td5hJ7qXvPEsFBGcvMYeL7haGBESGri",
  "amount": "15.00000000",
  "merchantAmount": "14.85000000",
  "coinCode": "DOGE",
  "networkCode": "dogecoin",
  "confirmationsCurrent": 25,
  "confirmationsRequired": 20,
  "txid": "19b7f4d117a10b192307aa2f441dac60be799880ee6fda8c771696e5d3a360fc",
  "blockNumber": 6398234,
  "blockTimestamp": "2026-10-01T14:56:00.000Z",
  "detectedAt": "2026-10-01T14:56:29.831Z",
  "confirmedAt": "2026-10-01T15:20:00.000Z",
  "occurredAt": "2026-10-01T15:20:00.000Z",
  "createdAt": "2026-10-01T14:56:29.831Z",
  "updatedAt": "2026-10-01T15:20:00.000Z"
}

Identify a deposit by uuid. Do not use txid as the only identifier: one transaction can contain several deposits.
walletAddressUuid identifies the address and staticWalletUuid the static wallet. Do not mix them up.

Example: payout.cancelled

{
  "type": "payout",
  "eventType": "payout.cancelled",
  "status": "cancelled",
  "isFinal": true,
  "coinCode": "USDT",
  "networkCode": "ethereum",
  "recipientAmount": "4.846587",
  "debitAmount": "4.951539"
}

For payout, the serviceFee field is not sent in webhooks.

Delivery

Your server response	Action
`2xx`	Delivered.
`408`, `429`, `5xx`, network errors, timeout, DNS	Delivery is retried.
Anything else, including `3xx` and `409`	Terminal failure, no retry.

By default there are 10 attempts, after which the event moves to dead_letter. Attempts use exponential backoff with random jitter from 0 to +20%:

delay = min(60000, 2^max(1, n) × 1000) ms + jitter

There is no fixed delay between attempts. Retries stop after a successful response or after the last attempt.

Handling on your side

Return 2xx only after the event is safely stored.
Redelivery of the same eventUuid must not credit funds twice — use it for deduplication.
Delivery order is not guaranteed: handle duplicates and out-of-order events.

URL requirements

HTTPS only.
Reachable from the internet.
Not localhost or a private IP.
No redirects — the service does not follow them.

← PreviousRetrieve a withdrawal Next →Signature verification