Skip to main content

Webhook Event

Overview

The Orders Webhook delivers real-time notifications about order status changes. When creating an order, provide a webhook URL via the callback parameter to receive automatic updates.

Setting Up Webhooks

Include the callback parameter when creating an order:
The webhook URL must be a valid HTTPS URL. Your endpoint should respond with HTTP 200 and within a 30-second timeout.

Webhook Payload

When an order status changes, Holdstation Pay sends a POST request to your webhook URL.

HTTP Headers

Payload Example

The type and timestamp fields are deprecated and will be removed in a future version. Use topic and ts instead.

Webhook Verification

To ensure webhook authenticity, verify the signature from the X-HSPay-Event-Signature header using your Webhook Checksum Key (provided by Holdstation Pay). The signature uses the Ed25519 cryptographic scheme on the entire request body.

Retry Mechanism

If your webhook endpoint returns a non-200 status code or times out:
  • Holdstation will retry up to 5 times
  • Retry intervals: 1, 2, 4, 8, 12 seconds
  • After 5 failed attempts, the webhook is marked as failed

Best Practices

Handle duplicate webhook calls gracefully using the order_id. Your system should process each order update only once.
Always verify the Ed25519 checksum signature before processing webhook payloads.
Respond quickly (under 30 seconds) to avoid timeouts. Process heavy logic asynchronously.
Return appropriate HTTP status codes. Use 200 for success, even if you queue the event for later processing.