Webhooks

Algopay sends signed POST requests to your endpoint when key events occur. Each delivery includes an X-Algopay-Signature header for verification.

Register

POST/webhooksJWT

Field	Type
url	string (url)	required
events	string[]	required — at least one event

GET/webhooksList all registered webhooksJWT

PATCH/webhooks/:webhookIdJWT

Field	Type
url	string	optional
events	string[]	optional
active	boolean	optional

DELETE/webhooks/:webhookIdJWT

POST/webhooks/:webhookId/rotate-secretIssue a new signing secretJWT

Events

Event	Fired when
payment_settled	On-chain group confirmed
payment_failed	Submission failed or reverted
pool_low	Pool balance drops below alertThresholdUsdc

// payment_settled payload
{
  "event": "payment_settled",
  "payment_id": "uuid",
  "invoice_id": "inv-001",
  "txn_id": "JYHEQ...",
  "amount_usdc": "1000000",
  "finality_ms": 4200,
  "gas_sponsored": true
}

Deliveries

GET/webhooks/:webhookId/deliveriesDelivery history with status codesJWT

POST/webhooks/deliveries/:deliveryId/retryRe-send a failed deliveryJWT

Signature verification

import crypto from 'crypto'

function verify(secret, rawBody, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}