Webhooks

Webhooks let you receive notifications when events happen in the Strictly platform — a payment is charged, refunded or voided, an invoice changes, a payment link is paid, or a subscription updates.

Instead of polling the API for status updates, configure a webhook URL and the Strictly API will POST the affected resource to your server automatically.

How it works

Actions

Payload fields

data is built from the resource and omits fields that are not set, so treat most fields as optional.

Payment (sale, auth, capture, refund, void): paymentId, clientId, clientName, orderId, order, currency, paid, amount, surcharge, percent, status, from, fromId, paidAmount, paidAmountSurcharge, amountRefunded, amountToRefund, surchargeRefunded, error, transactionErrorMsg, statusList, settled, transactionId, paidAt, paymentType, metadata, paymentMethod, avsResponse, cvvResponse, authCode. paymentMethod is { cardType, name, last4, exp, type } for cards and { accountType, last4 } for ACH. Amounts are integers in cents.

Invoice (invoice): invoiceNumber, amount, cost, paid, paidAmount, paidSurcharge, customValues, dueDate, currency, billingAddress, shippingAddress, tax, discount, products[], paymentRequestUrl, publicInvoiceUrl, status.

Payment link (paymentLink): paymentMethod, paid, amount, taxes, totalAmount, paymentLink, paymentId, paymentLinkId, transactionId, paidAmount, surcharge.

Use the ids in the payload (paymentId, transactionId, invoiceNumber, paymentLinkId) with the matching GET endpoint in the API Reference when you need the full, current resource.

Retries and reliability

If your endpoint returns a non-2xx response or the connection fails, delivery is retried up to three times:

After the third retry fails, the delivery is abandoned. Recover missed events by querying the relevant resource through the API.

Idempotency

Your webhook handler must be idempotent — the same delivery may arrive more than once, and a payment produces one delivery per action. There is no separate event id: build your own key from action plus the resource id (data.paymentId and data.transactionId for payments, data.invoiceNumber for invoices, data.paymentLinkId for payment links) and skip deliveries you have already handled.

Idempotent handler example
const processed = new Set(); // In production: use a database

async function processWebhookEvent(payload) {
  const { action, data } = payload;
  const key = `${action}:${data.paymentId ?? data.invoiceNumber ?? data.paymentLinkId}:${data.transactionId ?? ""}`;

  if (processed.has(key)) {
    console.log(`Skipping duplicate delivery: ${key}`);
    return;
  }

  processed.add(key);

  switch (action) {
    case "sale":
      if (data.paid) await fulfillOrder(data);
      else await notifyDecline(data);
      break;
    case "refund":
      await recordRefund(data);
      break;
    // ...
  }
}

Inbound webhooks

The Strictly API also accepts inbound webhooks from external integrations via the /public/webhooks/ endpoints. These allow third-party services to send payment-related events into the Strictly platform. See the API Reference for available inbound webhook routes and their expected payloads.