Webhooks Overview

Soap notifies your backend of checkout activity by sending an HTTP POST request with a JSON body to the webhook URL you configure in your dashboard. New to receiving webhooks? Start with Receiving Webhooks for setup steps and a minimal handler. Before writing a handler, read Checkouts, Charges and Reviews. Most events below report a transition of a charge, not of the checkout session, and one checkout can produce several charges — which determines what you should key your ledger on.

The Envelope

Every webhook delivery is a JSON object with three top-level keys. The wire key order is always event_id, data, type — note that data comes before type, even though it reads more naturally last.

Key	Description
`event_id`	Stable identifier for this logical event (format `ev_...`). Use it as your idempotency key — see Retries, Timeouts and Idempotency.
`data`	The event payload. Shape depends on the event `type` — see the event pages linked below.
`type`	The event type, e.g. `"checkout.succeeded"`.

data.type (inside the payload) is the checkout type — "deposit" or "withdrawal" — not the event type. It’s easy to confuse with the top-level type, which is the event name.

Here’s a complete, realistic checkout.succeeded delivery for a deposit with a populated line item:

{
  "event_id": "ev_tDaWu5aTVa2kbvDjGe55rxZpaMEmVFWB",
  "data": {
    "id": "chk_twijxXgVFofj9mdnvzF7vhbJSZEhfUpC",
    "line_items": [
      {
        "product_id": "prod_8KpQmZ3xRyVnTsUcWjLaGdBh",
        "quantity": 2,
        "total_amount_cents": 5000,
        "product_name": "Gold Coins Pack",
        "product_url": "https://example.com/products/gold-coins",
        "product_price_cents": 2500,
        "sku": "gold-coins-1000"
      }
    ],
    "line_items_total_amount_cents": 5000,
    "type": "deposit",
    "charge": {
      "id": "ch_yRZcCGouimTgbz4thtrfbj2mh3ZT6vnz",
      "amount_cents": 5000,
      "transaction_type": "credit",
      "status": "succeeded",
      "from_status": "created",
      "failure_code": null,
      "failure_message": null
    },
    "customer": {
      "id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870"
    },
    "subscription": null
  },
  "type": "checkout.succeeded"
}

charge.failure_code and charge.failure_message are present on every charge-based event and are null when there’s no failure. subscription is present on every one of the 12 events — it’s null for non-subscription checkouts, otherwise an object describing the recurring plan.

Events

Soap sends 12 event types. Four are always sent and cannot be disabled. The other eight are off by default and will never fire until you enable them. Not every charge status has an event: a charge that becomes cancelled or refunded is not notified. See the charge status lifecycle for the full status-to-event mapping.

Event	Description	Delivery
`checkout.succeeded`	A deposit or withdrawal succeeded.	Always sent
`checkout.hold`	During a withdrawal, Soap asks you to place a hold on the available balance to prevent double spending.	Always sent
`checkout.release_hold`	A withdrawal failed after a hold had been placed.	Always sent
`checkout.returned`	A payment was returned (e.g. an ACH bounce) after it had succeeded.	Always sent
`checkout.pending`	A checkout session entered a pending state.	Off by default
`checkout.failed`	A deposit or withdrawal failed.	Off by default
`checkout.voided`	A charge was voided after it had previously succeeded.	Off by default
`checkout.expired`	A checkout session expired before completion.	Off by default
`checkout.terminally_failed`	A checkout failed due to geo, KYC, or other fraud checks and cannot be continued.	Off by default
`checkout.review.created`	A payment was flagged for manual review.	Off by default
`checkout.review.approved`	A customer support agent approved a review.	Off by default
`checkout.review.declined`	A customer support agent declined a review.	Off by default

The 8 events marked off by default are silently never delivered until you enable them in Dashboard → Developers. If you write a handler for one of these (e.g. checkout.failed) and it never fires, this is why. See Receiving Webhooks for how to enable them.

Verifying Webhook Signatures

To prevent malicious actors from sending you fake events, every delivery includes a signature. Soap sends the identical signature value in two headers:

Header	Notes
`SOAP-WEBHOOK-SIGNATURE`	Canonical header. Prefer this one.
`SOAP_SIGNATURE`	Legacy alias carrying the same value. Sent on every delivery for backwards compatibility.

There is no separate timestamp header and no event-id header — the timestamp is embedded in the signature value, and event_id is in the body. Both headers use the same format:

t=1673979302,v1=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

t is the Unix timestamp when the signature was generated.
v1 is the signature itself, an HMAC-SHA256 hex digest.

The signed message is "<timestamp>.<raw_request_body>" — the timestamp, a literal period, then the exact raw bytes of the request body. Recompute this using your webhook signing secret (wss_..., from Dashboard → Developers) and compare it to the received signature.

The signature covers Soap’s exact serialized bytes, not your parsed-and-re-serialized JSON. If your framework parses the JSON body before your handler runs, and you then call JSON.stringify/.to_json to recompute the signature, verification will fail — key order and whitespace differ from what Soap actually sent.In Express, use express.raw({ type: 'application/json' }) on the webhook route (instead of the global express.json() middleware) so req.body is the untouched Buffer of raw bytes:

app.post('/webhooks/soap', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = req.body.toString('utf8'); // raw bytes — do not JSON.parse and re-serialize
  // ... verify signature against `payload` ...
});

Every framework has an equivalent need: read the body as raw bytes (or a raw string) for signature verification before any middleware parses and reconstructs it as an object.

import crypto from 'crypto';

function verifySignature(payload: string, signatureHeader: string, signingSecret: string): boolean {
  const parts = signatureHeader.split(",");
  const timestampPart = parts.find((p) => p.startsWith("t="));
  const signaturePart = parts.find((p) => p.startsWith("v1="));

  if (!timestampPart || !signaturePart) {
      return false;
  }

  const timestamp = timestampPart.split("=")[1];
  const receivedSignature = signaturePart.split("=")[1];

  // timingSafeEqual throws if the two buffers differ in length, so reject
  // anything that is not a full SHA-256 hex digest before comparing.
  if (!/^[0-9a-f]{64}$/i.test(receivedSignature)) {
      return false;
  }

  // Create the signature message
  const message = `${timestamp}.${payload}`;

  // Calculate signature
  const calculatedSignature = crypto
      .createHmac("sha256", signingSecret)
      .update(message)
      .digest("hex");

  // Compare signatures using a timing-safe comparison
  return crypto.timingSafeEqual(
      Buffer.from(receivedSignature, "hex"),
      Buffer.from(calculatedSignature, "hex")
  );
}

require 'openssl'
require 'active_support/security_utils'

def verify_signature(payload, signature_header, signing_secret)
  parts = signature_header.split(',')
  timestamp = parts.find { |p| p.start_with?('t=') }&.split('=', 2)&.last
  received_signature = parts.find { |p| p.start_with?('v1=') }&.split('=', 2)&.last

  return false unless timestamp && received_signature

  # Create the signature message
  message = "#{timestamp}.#{payload}"

  # Calculate signature
  calculated_signature = OpenSSL::HMAC.hexdigest("SHA256", signing_secret, message)

  # Compare signatures using a timing-safe comparison
  ActiveSupport::SecurityUtils.secure_compare(received_signature, calculated_signature)
end

If the signatures don’t match you should reject the webhook and not process it.

Updating Your Internal Ledger

It depends on how you implement your accounting system. In this example, we only use credits and debits and update the customer’s balance or internal ledger accordingly.

Retries, Timeouts and Idempotency

Each delivery attempt has a 10 second timeout.
Soap retries up to 5 total attempts (the initial attempt plus 4 retries) for events that fail or time out.
checkout.hold is delivered synchronously and is never retried — see checkout.hold for why your response status matters.
Each delivery attempt generates a new timestamp and therefore a new signature — even retries of the same logical event will have a different SOAP-WEBHOOK-SIGNATURE value.
event_id is stable for a given logical event across all of its delivery attempts. Use it as your idempotency key so you don’t reprocess the same event twice.

API Documentation

API Endpoints

Webhooks

Testing

Webhooks Overview

The Envelope

Events

Verifying Webhook Signatures

Updating Your Internal Ledger

Retries, Timeouts and Idempotency

​The Envelope

​Events

​Verifying Webhook Signatures

​Updating Your Internal Ledger

​Retries, Timeouts and Idempotency

The Envelope

Events

Verifying Webhook Signatures

Updating Your Internal Ledger

Retries, Timeouts and Idempotency