Real-Time Payment Events
Webhooks deliver instant notifications when events occur in the Surfboard ecosystem. Payment completed? NFC tap detected? Refund processed? Your systems know immediately. Build reactive, event-driven payment flows without polling.
Event-Driven Architecture
Modern payment integrations shouldn't require constant polling to know what happened. Surfboard's webhook system pushes events to your servers the moment they occur, with real-time parity to our internal infrastructure.
Every webhook includes complete transaction context: amounts, currencies, payment methods, customer data, terminal information, and any custom metadata you attached. Your backend has everything it needs to process the event without additional API calls.
Reliable delivery, guaranteed
Our webhook system includes automatic retries with exponential backoff, delivery signatures for security verification, and detailed logging so you can debug any delivery issues. Events are queued and redelivered until your endpoint confirms receipt.
How Webhooks Work
Register your endpoint
POST /webhooks
{
"url": "https://your-server.com/webhooks",
"events": [
"order.paymentcompleted",
"order.paymentfailed",
"order.customer.identify"
]
}Events fire in real-time
Process and respond
{
"eventType": "order.paymentcompleted",
"metadata": {
"eventId": "831fc2f040bf405fff",
"created": 1745821536443,
"retryAttempt": 0
},
"data": {
"orderId": "831fc2de72fed0000b",
"paymentStatus": "PAYMENT_COMPLETED",
"paymentMethod": "CARD",
"amount": "310"
}
}Events for every scenario
Surfboard webhooks cover the complete payment lifecycle plus unique events like NFC reads and identification. Subscribe only to what you need.
Payment Events
Track the complete payment lifecycle:
order.paymentinitiatedorder.paymentprocessedorder.paymentcompletedorder.paymentfailedorder.paymentcancelled
Each one carries the order, the payment status, the amount and the terminal that triggered it. The completed event also carries full transaction details: card brand, truncated PAN, RRN and the authorization response.
Order Events
Follow the order itself, not just the money:
order.updated- Any attribute of the order changedorder.cancelled- The order was cancelled
Useful when the order is edited between creation and payment, which is exactly the window identification opens up.
Identification & Terminal Events
Build physical-to-digital experiences:
order.customer.identify- Card tapped, token returnedorder.terminal.event- Every terminal state in a transaction
The identify event carries the order and a tokenized cardId before the payment is processed, so you have a window to recognize the customer and change the order. The terminal event covers tip selection, card presented, PIN entry and authorizing, online states included.
Logistics Events
Know where the hardware is:
logistics.orderupdate- Shipment status changed
Fires on ORDER_PLACED, ORDER_SHIPPED, ORDER_COMPLETED and ORDER_PENDING_FOR_STOCK. A shipped order carries a tracking URL and the serial numbers in the box.
Merchant Application Events
Track onboarding without polling the application:
- Application initiated, submitted and signed
- Started, and pending merchant information
- Completed, merchant created
- Expired or rejected
Enough to drive an onboarding UI end to end, from the signing link going out to the Merchant ID coming back.
Custom Event Metadata
Attach your data to every event:
- Order references from your system
- Customer IDs for matching
- Custom fields for your workflow
Whatever metadata you send with the order comes back in every webhook, making reconciliation seamless.
Why developers love our webhooks
Events fire milliseconds after they occur. No polling delays.
Delivery signatures let you verify events came from Surfboard.
Automatic retries with exponential backoff. Events don't get lost.
Complete transaction data in every event. No extra API calls needed.
Same events, every channel
Whether a payment happens on a terminal, online checkout, SoftPOS device, or unattended kiosk, you receive the same webhook structure. Build your event handlers once and they work across all acceptance types.
This is unified commerce in action: consistent data models across every channel.
Start receiving events
Configure your webhook endpoints and start receiving real-time payment events. Our documentation includes event schemas, signature verification, and best practices for building reliable webhook handlers.
// Example webhook payload
{
"eventType": "order.paymentcompleted",
"metadata": {
"eventId": "831fc2f040bf405fff",
"created": 1745821536443,
"retryAttempt": 0,
"terminalId": "830acac336f6d80b04"
},
"data": {
"orderId": "831fc2de72fed0000b",
"merchantId": "82e48bd833d7d80c0e",
"referenceId": "r_3",
"paymentStatus": "PAYMENT_COMPLETED",
"paymentMethod": "CARD",
"amount": "310",
"transactionDetails": [
{
"cardBrand": "MASTERCARD",
"truncatedPan": "0102",
"currency": "752"
}
]
}
}Build it yourself
Step-by-step developer guides for everything on this page.
Receive real-time event notifications via webhooks. Subscribe to order, payment, logistics, and merchant application events with automatic retries and signature verification.
Read guide Online · GuideSubscribe to persistent, account-level event notifications delivered via email, Slack, or SFTP. Receive settlement reports and operational alerts for merchants and partners.
Read guide Online · GuideManage the full payment lifecycle from order creation through capture, void, cancel, and refund operations using the Surfboard Payments API.
Read guide