Webhook glossary

Mass payment file process is completed

If you have uploaded a file for bulk payments, it takes some time to process the file. Rather than waiting for this process to complete and rechecking its status, you can subscribe to a real time notification about this event via this webhook.

Example

{
  "eventName": "mass_payment_file_processed",
  "data": {
    "processed": true
  }
}

Mass sending of the payments is completed

Once your mass payment file is processed, you can send all valid payments. With this webhook, you can subscribe to the asynchronous result of your mass payment. Once all valid payments are sent, this webhook will trigger.

Example

{
  "eventName": "mass_payments_sent",
  "data": {
    "sent": true
  }
}

Payment status changed

When you send a payment, a new payment is created with an initial status, like Awaiting-cash-out. This status will be changed depending on what event is currently taking place for his payment. When the status of this payment changes, the webhook for this event will be launched for the sender and recipient of this payment. It contains basic information: id, from, to, amount and status.

Example

{
  "eventName": "payment_status_changed",
  "data": {
    "id": 1,
    "from": "[email protected]",
    "to": "[email protected]",
    "amount": 12.34,
    "status": "Awaiting-cash-out"
  }
}

Invoice status changed

When you create an invoice, it is assigned an initial status that changes as the invoice moves through its lifecycle (for example, when a payment link is sent or the invoice is paid). Whenever the status of one of your invoices changes, this webhook fires with the full invoice details, including the related policyholder, carrier, and MGA. The status field is the human-readable invoice status name (for example, direct_payment_paid).

📘

Status format

The readable status name is being rolled out. Until that change is fully deployed, the status field may instead arrive as the numeric status code as a string (for example, "12" for direct_payment_paid). We recommend handling both formats during the transition.

Example

{
  "eventName": "invoice_status",
  "data": {
    "id": "1",
    "status": "direct_payment_paid",
    "grossPremium": 1000,
    "commission": 100,
    "netPremium": 900,
    "policyId": "POL-12345",
    "brokerCode": "BRK-001",
    "effectiveDate": "2026-01-01T00:00:00.000Z",
    "expirationDate": "2027-01-01T00:00:00.000Z",
    "stripeSubscriptionId": null,
    "policyholder": {
      "email": "[email protected]",
      "firstName": "Jane",
      "lastName": "Doe",
      "businessName": null
    },
    "carrier": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Smith",
      "businessName": null
    },
    "mga": null
  }
}

Card charge status changed

Subscribe with event ID 7 to receive updates when a card charge settles, completes, fails, or changes state because of a confirmed refund. See card charge statuses for the meaning of each status. The payload contains the original payer receipt, not a merchant fee statement or net settlement amount.

Example

Illustrative completed $1 charge without a surcharge:

{
  "eventName": "card_charge_status_changed",
  "data": {
    "chargeId": 14,
    "status": "succeeded",
    "failureCode": null,
    "failureMessage": null,
    "card": { "brand": "Visa", "lastFour": "3000" },
    "receipt": {
      "subtotalCents": 100,
      "surchargeCents": 0,
      "taxCents": 0,
      "tipCents": 0,
      "totalCents": 100,
      "currency": "USD"
    },
    "metadata": null
  }
}

Card refund status changed

Subscribe with event ID 8 for card refund processing, completion, or failure updates. receipt remains the original charge receipt. The separate refunded object reports confirmed returned funds only: all three amounts are zero while the refund is processing or failed.

Example

Illustrative completed full refund of the $1 charge above:

{
  "eventName": "card_charge_refund_status_changed",
  "data": {
    "chargeId": 14,
    "refundId": 9,
    "status": "succeeded",
    "failureCode": null,
    "failureMessage": null,
    "receipt": {
      "subtotalCents": 100,
      "surchargeCents": 0,
      "taxCents": 0,
      "tipCents": 0,
      "totalCents": 100,
      "currency": "USD"
    },
    "refunded": {
      "principalCents": 100,
      "surchargeCents": 0,
      "totalCents": 100
    }
  }
}

Handle card deliveries safely

Configure an active subscription with selectedEvents: [7, 8] and a secret, and validate each signature. Use failureCode for programmatic failure handling and failureMessage for a readable explanation.

Deliveries can be duplicated or delayed, and retries are bounded; there is no guarantee of exactly-once delivery or unlimited retry. Make repeated events safe using the charge or refund ID and status. Do not assume callback arrival order is the order of processor transitions, and do not require every intermediate state to arrive before handling completion. Use GET card charge to reconcile when events are missing, delayed, or inconsistent with your last known state.

Account verification status changed

The onboarding process for verified users in ClaimsSnap an asynchronous KYB process. This webhook lets you subscribe to your account verification status in real time after you've signed up and submitted your information for verification.

Example

{
  "eventName": "verification_status_changed",
  "data": {
    "status": "verified"
  }
}

Beneficial owners status changed

If you are an organization, you will need to go through an additional verification process after confirming your account. Depending on your entity circumstances, you may need to verify beneficial owners that hold significant equity in your business.

This webhook lets you subscribe to the status of beneficial ownership validation for your account.

Example

{
  "eventName": "bo_status_changed",
  "data": {
    "status": "certified"
  }
}