Webhooks

Suward pushes signed events to your endpoint as payments and static-wallet deposits progress on-chain. Verify each one and use it to advance your own order state.

Delivery

Set the destination once per project, or override it for a single payment or static wallet.

webhookUrl

Configure a project-wide URL in the dashboard, or override it per payment or per static wallet via the webhookUrl field. If neither is set, no delivery is created.

Transport

Each event is an HTTP POST with a JSON body. The URL must be https:// and resolve to a public host.

Retries

Delivery is at-least-once with retries. Make your handler idempotent — deduplicate on eventId.

Verify the signature

Every request is signed so you can trust it came from Suward and was not replayed.

Header

X-Suward-Signature: ed25519=<hex signature over the raw request body>

Algorithm

Ed25519 over the raw request body. Verify with your project's webhookPublicKey (from the dashboard) before parsing the JSON.

Replay window

Reject events whose timestamp is more than 300 seconds from now.

Events

Events are grouped by the resource that emitted them. Only stage changes are delivered.

Payments

payment.accepted

Safe confirmations reached — safe to release goods or services.

payment.success

Finalized on-chain — funds credited to your project balance.

payment.failed

Expired, cancelled, or invalidated by a chain reorganization.

Static Wallets

static_deposit.accepted

A deposit into a static wallet reached safe confirmations.

static_deposit.success

A static-wallet deposit finalized and was credited to your balance.

Example payload

payment.success

{
  "type": "payment.success",
  "eventId": "evt_abc123",
  "createdAt": 1730000000000,
  "payment": {
    "id": "pay_abc123",
    "status": "success",
    "subStatus": "completed",
    "asset": "USDT_ETHEREUM",
    "amount": "100000000",
    "amountReceived": "100000000"
  }
}

Static-wallet events mirror this shape with a deposit object instead of payment.