Webhooks

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

Configure your webhook URL in the Merchant Portal or via API. Select which events you want to receive.

                          POST /webhooks
{
  "url": "https://your-server.com/webhooks",
  "events": [
    "order.payment.completed",
    "order.payment.failed",
    "nfc.tags.read"
  ]
}

Events fire in real-time

When something happens in the Surfboard ecosystem, we immediately POST the event to your endpoint with full transaction context.

Process and respond

Your server processes the event and returns a 2xx response. We handle retries automatically if delivery fails.

                          {
  "event": "order.payment.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "amount": 4999,
    "currency": "EUR",
    "paymentMethod": "card"
  }
}

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.payment.initiated
order.payment.processing
order.payment.completed
order.payment.failed
order.payment.cancelled

Every event includes full transaction metadata: amount, currency, payment method, terminal ID, and custom metadata you attached to the order.

NFC & Identification Events

Build physical-to-digital experiences:

nfc.tags.read - NFC tag detected
card_identified - Card tap for ID

Perfect for loyalty check-in, access control, staff tracking, or any scenario where a tap triggers business logic without a payment.

Refund Events

Stay informed when money moves back:

order.refunded
order.partially_refunded

Update your systems automatically when refunds complete. No polling required.

Report Events

Automated reporting webhooks:

transaction.report - Report ready
Daily, weekly, or monthly reports
SFTP delivery confirmations

Integrate Surfboard data directly into your BI pipeline.

Terminal Events

Monitor your device fleet:

Terminal online/offline status
Device identification events
Configuration updates

Keep your operations team informed about terminal health without manual checks.

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

⚡

Real-Time

Events fire milliseconds after they occur. No polling delays.

🔒

Signed

Delivery signatures let you verify events came from Surfboard.

🔄

Retry Logic

Automatic retries with exponential backoff. Events don't get lost.

📊

Full Context

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.

Explore the API docs

                            // Example webhook payload
{
  "event": "order.payment.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=...",
  "data": {
    "orderId": "ord_abc123",
    "merchantId": "mer_xyz789",
    "amount": 4999,
    "currency": "EUR",
    "paymentMethod": {
      "type": "card",
      "brand": "visa",
      "last4": "4242"
    }
  }
}

Related Platform Features

Unified Commerce

One API for all channels

Customer API

Unified customer profiles

Identification

Identify customers by card tap

Billing API

Custom pricing for ISVs