Search docs

Search the API documentation

Webhooks

Artos sends webhook notifications to your registered endpoints when payment events occur. Configure webhook URLs from your Dashboard → Webhooks.

Events

EventDescription
payment.successPayment completed successfully
payment.failedPayment failed or was rejected
payment.expiredPayment window expired

Payload

Artos sends a POST request with the following JSON body to your webhook URL.

payment.success
{
  "event": "payment.success",
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "merchantOrderId": "ORDER-001",
    "amount": 50000,
    "status": "paid",
    "reference": "DK-12345"
  }
}
payment.failed
{
  "event": "payment.failed",
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "merchantOrderId": "ORDER-001",
    "amount": 50000,
    "status": "failed",
    "reference": "DK-12345"
  }
}
payment.expired
{
  "event": "payment.expired",
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "merchantOrderId": "ORDER-001",
    "amount": 50000,
    "status": "expired",
    "reference": "DK-12345"
  }
}

Headers

Each webhook request includes a signature header for verification.

Content-Typeheader

Always application/json

X-Artos-Signatureheader

HMAC-SHA256 signature of the raw request body (hex-encoded), signed with your webhook secret.

Delivery & Retry

Artos delivers webhooks with at-least-once semantics. If your endpoint returns a non-2xx status or times out (10 second limit), the delivery is marked as failed. You can manually retry from Webhook Logs. Make your handler idempotent using transactionId.