Overview

Each time a gateway action completes, an HTTP POST request is sent to the webhook URL configured for the location. The request body is a JSON object describing the event, and the headers carry a signature you use to confirm the notification is authentic.

Supported events

The event type is always present in the event field of the payload.

Request headers

Verifying the signature

Every request is signed so you can confirm it was sent by the gateway and was not altered in transit.

🚧

Always verify before trusting the payload

Never process a webhook whose signature fails verification. Keep your signing secret private: never expose it in client-side code, logs, or public repositories.

Signature header format

x-softpoint-signature: t=<UNIX_TIMESTAMP>,v1=<SIGNATURE>

Verification steps

1. Read the raw request body exactly as received.
2. Parse the x-softpoint-signature header and extract t and v1.
3. Build the signed payload by joining the timestamp and the raw body with a period: <t>.<raw_body>.
4. Compute an HMAC-SHA256 of the signed payload using your webhook signing secret as the key, and hex-encode the result.
5. Compare your result with v1 using a constant-time comparison.
6. Reject the request if the timestamp is older than your tolerance window (300 seconds recommended) to protect against replay attacks.

❗️

Use the raw body

Do not parse and re-serialize the JSON before computing the signature. Any change in whitespace or key order will make verification fail.

Code examples

<?php
$secret    = getenv('SOFTPOINT_WEBHOOK_SECRET');
$rawBody   = file_get_contents('php://input');
$header    = $_SERVER['HTTP_X_SOFTPOINT_SIGNATURE'] ?? '';
$tolerance = 300; // seconds

$parts = [];
foreach (explode(',', $header) as $pair) {
    [$k, $v] = array_pad(explode('=', $pair, 2), 2, null);
    $parts[trim($k)] = trim((string) $v);
}

if (empty($parts['t']) || empty($parts['v1'])) {
    http_response_code(400);
    exit('Invalid signature header');
}

if (abs(time() - (int) $parts['t']) > $tolerance) {
    http_response_code(400);
    exit('Timestamp outside tolerance');
}

$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);

if (!hash_equals($expected, $parts['v1'])) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($rawBody, true);
// Process $event ...
http_response_code(200);

const express = require('express');
const crypto = require('crypto');

const app = express();
const SECRET = process.env.SOFTPOINT_WEBHOOK_SECRET;
const TOLERANCE = 300; // seconds

app.post('/webhooks/gateway', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('x-softpoint-signature') || '';
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('=').map(s => s.trim()))
  );

  if (!parts.t || !parts.v1) return res.status(400).send('Invalid signature header');

  if (Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t)) > TOLERANCE) {
    return res.status(400).send('Timestamp outside tolerance');
  }

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${parts.t}.${req.body.toString('utf8')}`)
    .digest('hex');

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(parts.v1, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  // Process event ...
  res.sendStatus(200);
});

app.listen(3000);

Responding to webhooks

Return a 2xx status code (for example 200 OK) as soon as the request has been received and verified. Any other status code, or a timeout, is treated as a failed delivery.

📘

Best practices

• Respond fast. Queue the event and return 200 immediately; do heavy processing asynchronously.
• Be idempotent. The same event may be delivered more than once. Use transaction_id + event to detect duplicates (token + event for tokenizations, and transaction_id + transaction_status for ACH).
• Don't rely on order. Events may arrive out of order; for example, a capture may arrive before you finish processing its authorization.

Payload fields

Every payload contains event and location_id. The table below shows which fields each event includes.

🚧

Parsing notes

• amount is a string with two decimals. Parse it as a decimal, never as a float.
• currency is an ISO 4217 code that may arrive in upper or lower case. Compare it case-insensitively.
• guest_id and token can be null. Always handle the null case.

Events

gateway.sale.completed

Sent when a sale (authorization and capture in a single step) has been processed.

{
  "location_id": <LOCATION_ID>,
  "transaction_id": <TRANSACTION_ID>,
  "amount": "<AMOUNT>",
  "currency": "<CURRENCY>",
  "processor_code": "<PROCESSOR_CODE>",
  "transaction_status": "<TRANSACTION_STATUS>",
  "guest_id": <GUEST_ID | null>,
  "token": "<TOKEN>" | null,
  "event": "gateway.sale.completed"
}

POST <YOUR_WEBHOOK_PATH> HTTP/1.1
Host: <YOUR_DOMAIN>
Content-Type: application/json
Content-Length: <CONTENT_LENGTH>
User-Agent: <USER_AGENT>
X-Softpoint-Client-Key: <CLIENT_KEY>
X-Softpoint-Timestamp: <UNIX_TIMESTAMP>
X-Softpoint-Signature: t=<UNIX_TIMESTAMP>,v1=<SIGNATURE>

gateway.authorization.completed

Sent when an authorization has been processed. An authorization places a hold on the funds but does not move them. The funds are later collected with a capture or released with a void.

{
  "location_id": <LOCATION_ID>,
  "transaction_id": <TRANSACTION_ID>,
  "amount": "<AMOUNT>",
  "currency": "<CURRENCY>",
  "processor_code": "<PROCESSOR_CODE>",
  "transaction_status": "<TRANSACTION_STATUS>",
  "guest_id": <GUEST_ID | null>,
  "token": "<TOKEN>" | null,
  "event": "gateway.authorization.completed"
}

gateway.capture.completed

Sent when a capture of a previous authorization has been processed. The capture is a new transaction with its own transaction_id and points back to the authorization through original_transaction_id.

📘

Partial captures

The captured amount can be lower than the authorized amount.

{
  "location_id": <LOCATION_ID>,
  "transaction_id": <TRANSACTION_ID>,
  "original_transaction_id": <ORIGINAL_TRANSACTION_ID>,
  "amount": "<AMOUNT>",
  "currency": "<CURRENCY>",
  "processor_code": "<PROCESSOR_CODE>",
  "transaction_status": "<TRANSACTION_STATUS>",
  "guest_id": <GUEST_ID | null>,
  "token": "<TOKEN>" | null,
  "event": "gateway.capture.completed"
}

gateway.void.completed

Sent when a transaction has been voided. A void cancels a transaction before it settles, for example by releasing an authorization hold. The void is a new transaction with its own transaction_id and points back to the voided transaction through original_transaction_id.

{
  "location_id": <LOCATION_ID>,
  "transaction_id": <TRANSACTION_ID>,
  "original_transaction_id": <ORIGINAL_TRANSACTION_ID>,
  "amount": "<AMOUNT>",
  "currency": "<CURRENCY>",
  "processor_code": "<PROCESSOR_CODE>",
  "transaction_status": "<TRANSACTION_STATUS>",
  "guest_id": <GUEST_ID | null>,
  "token": "<TOKEN>" | null,
  "event": "gateway.void.completed"
}

gateway.refund.completed

Sent when a refund has been processed. A refund returns funds from a transaction that has already settled. The refund is a new transaction with its own transaction_id and points back to the refunded transaction through original_transaction_id.

📘

Void vs. refund

Use a void to cancel a transaction before it settles; use a refund to return money after it settles. Each produces its own event.

{
  "location_id": <LOCATION_ID>,
  "transaction_id": <TRANSACTION_ID>,
  "original_transaction_id": <ORIGINAL_TRANSACTION_ID>,
  "amount": "<AMOUNT>",
  "currency": "<CURRENCY>",
  "processor_code": "<PROCESSOR_CODE>",
  "transaction_status": "<TRANSACTION_STATUS>",
  "guest_id": <GUEST_ID | null>,
  "token": "<TOKEN>" | null,
  "event": "gateway.refund.completed"
}

gateway.tokenize.completed

Sent when a card has been tokenized and stored. No money moves in this event, so the payload has no transaction_id, amount, currency, processor_code, or transaction_status. Instead, it carries the token and non-sensitive card details you can show to the customer (for example, brand and last four digits).

{
  "location_id": <LOCATION_ID>,
  "token": "<TOKEN>",
  "card_type_id": <CARD_TYPE_ID>,
  "guest_id": <GUEST_ID | null>,
  "card_bin": "<CARD_BIN>",
  "last4": "<LAST4>",
  "card_exp_month": "<MM>",
  "card_exp_year": "<YY>",
  "customer_id_external": "<CUSTOMER_ID_EXTERNAL>",
  "event": "gateway.tokenize.completed"
}

📘

Keep card fields as strings

Store card_bin, last4, card_exp_month, and card_exp_year as strings to preserve leading zeros.

Card types

ach.status.changed

Sent when the status of an ACH transaction changes. ACH payments settle over several days, so a single ACH transaction can produce this event more than once as its status moves through its lifecycle. Always use the latest transaction_status received for a given transaction_id.

This payload has no amount, currency, processor_code, or original_transaction_id. Use transaction_id to look up the transaction details in your system.

{
  "transaction_id": <TRANSACTION_ID>,
  "location_id": <LOCATION_ID>,
  "guest_id": <GUEST_ID | null>,
  "token": "<TOKEN>" | null,
  "transaction_status": "<TRANSACTION_STATUS>",
  "event": "ach.status.changed"
}

🚧

Handle repeated events

Because one ACH transaction can generate several ach.status.changed events, deduplicate on transaction_id + transaction_status, not on transaction_id alone.

Testing

To inspect requests before building your endpoint, point the location's webhook URL to a request-inspection service such as webhook.site, trigger a gateway action, and review the headers and body that arrive. Once your endpoint is ready, switch the URL to your own server and confirm that signature verification passes.