Webhooks

Overview

Webhooks let your application receive real-time notifications when events occur — a card charge completes, a recurring payment fails, an invoice is paid. Instead of polling the API, Dime Payments pushes event data to a URL you specify.

Setting up a webhook

Log into the Dime Payments dashboard
Navigate to Advanced > Webhooks
Click Add Endpoint
Enter your publicly accessible HTTPS URL
Select the event this endpoint should receive
Save

Your endpoint must return a 200 response within 15 seconds or the attempt is considered failed. Do any real work asynchronously — acknowledge the delivery first, then process it on a queue.

One endpoint per event

Dime Payments registers each webhook against a single event. Payloads do not carry an event-name field, so you cannot inspect the body to tell which event fired. Instead, register a separate endpoint URL for each event you care about and identify the event by which URL received the delivery. For example, point Credit Card Charge at https://yourapp.com/hooks/card-charge and Invoice Paid at https://yourapp.com/hooks/invoice-paid, then handle each route separately.

Event types

These are the events you can subscribe to, grouped the way they appear in the dashboard. Each name is the exact string shown when you add an endpoint. Every group has a Select all option.

Onboarding

Event	When it fires
`Application Status Changed`	A merchant moves to a new onboarding stage. See Application Status Changed

Credit card

Event	When it fires
`Credit Card Charge`	A card charge completes
`Credit Card Refund`	A card refund is processed
`Credit Card Void`	A card transaction is voided, including a released authorization
`Credit Card Chargeback`	A chargeback is filed against a card transaction. For new integrations, use the Chargebacks events below
`Credit Card Authorize`	A hold is placed on a card. See Authorize and Capture
`Credit Card Capture`	A held authorization is captured

Chargebacks

Event	When it fires
`Chargeback Opened`	A new chargeback is filed against the merchant
`Chargeback Updated`	A chargeback changes, for example its representment status
`Chargeback Resolved`	A chargeback is decided

Risk retrievals

Event	When it fires
`Risk Retrieval Opened`	The card issuer requests documentation for a transaction
`Risk Retrieval Updated`	A retrieval request changes
`Risk Retrieval Resolved`	A retrieval request is closed

Chargeback and retrieval data comes from the processor in a once-daily file, so these events fire after that import, not the moment the bank acts. Send evidence for either one through Upload Documents with doc_type set to RetrievalRequest.

Credit Card Chargeback still fires for existing subscriptions, alongside the Chargebacks events. It only covers a chargeback being filed. The Chargebacks events also tell you when one changes or is decided.

ACH

Event	When it fires
`ACH Charge`	An ACH charge is submitted
`ACH Payment Return`	An ACH payment is returned
`ACH Refund`	An ACH refund is processed
`Deposit Sent`	Funds are deposited to the merchant bank account

Recurring payments

Event	When it fires
`Recurring Success`	A scheduled recurring payment succeeds
`Recurring Failed`	A scheduled recurring payment fails
`Recurring Cancelled`	A recurring payment is cancelled
`Recurring Paused`	A recurring payment is paused

Invoicing

Event	When it fires
`Invoice Created`	An invoice is created
`Invoice Updated`	A draft invoice is edited
`Invoice Sent`	An invoice is sent to the customer
`Invoice Paid`	An invoice is paid in full
`Invoice Payment Returned`	The customer’s bank returns an ACH payment made on an invoice. The invoice is reopened, because the money never arrived
`Invoice Voided`	An invoice is voided
`Invoice Deleted`	A draft invoice is deleted
`Recurring Invoice Created`	A recurring invoice template is created
`Recurring Invoice Cancelled`	A recurring invoice template is cancelled

Subscriptions

Event	When it fires
`Subscription Created`	A customer is enrolled in a plan
`Subscription Renewed`	A subscription renews for another period
`Subscription Payment Failed`	A subscription renewal is declined, or the bank returns a subscription’s ACH payment
`Subscription Paused`	A subscription is paused
`Subscription Resumed`	A paused subscription resumes
`Subscription Cancelled`	A subscription is cancelled

Held funds

For merchants on a held funds setup. A release sends one of these as soon as its outcome is saved.

Event	When it fires
`Funds Released`	A release was sent to the merchant’s bank account
`Funds Release Failed`	A release was declined and nothing moved
`Funds Release Unconfirmed`	No confirmation came back, and the release may have gone through. See Held funds releases

Payload format

The request body is a flat JSON object. The event data is sent at the top level — there is no envelope wrapping it. A transaction webhook:

{
  "transaction_type": "CC",
  "transaction_status": "Success",
  "transaction_status_description": "Approved",
  "transaction_number": "1234567890",
  "transaction_date": "2026-01-01T00:00:00.000000Z",
  "amount": "49.99",
  "customer_uuid": "66f1c230-1337-4g59-b43c-1bcb83adfaaa",
  "transaction_info_id": "9876543210",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "addr1": "123 Main St",
    "city": "Atlanta",
    "state": "GA",
    "zip": "30301"
  }
}

An invoice webhook:

{
  "company_sid": "000010",
  "type": "invoice_paid",
  "id": 4021,
  "invoice_number": "INV-0007",
  "status": "paid",
  "payment_terms": "net_15",
  "issue_date": "2026-07-01",
  "due_date": "2026-07-16",
  "subtotal": 250.0,
  "total": 250.0,
  "amount_paid": 250.0,
  "balance": 0.0,
  "customer": {
    "uuid": "9f2a6c14-3e8b-4d21-9a77-5c1e0b8f4d33",
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "items": []
}

Every payload carries company_sid, the merchant the event belongs to. Invoice, recurring invoice, subscription, recurring payment and held funds payloads also carry type, the event in snake_case (invoice_paid, invoice_payment_returned, funds_released, …). Transaction, ACH and deposit payloads do not.

Application Status Changed

Fires every time a merchant moves to a new onboarding stage. The payload carries the same fields as Get Application Status:

Field	Meaning
`sid`	The merchant
`name`	The merchant’s name
`status`	The onboarding stage: `lead`, `discovery`, `proposal`, `application_in_progress`, `underwriting`, `live`, `cancellation_pending`, `churned`, or `declined`
`application_status`	The application itself: `draft`, `pending_review`, `submitted`, `approved`, `needs_documents`, `failed`, or `null` if none has been started
`boarded`	Whether the merchant can take money
`application_submitted_at`	When the application went to the processor, or `null`

When status is underwriting, read application_status. Only needs_documents means you need to do something. And use boarded as the signal that the merchant is ready to take payments: a merchant can be live without application_status being approved. Subscribe to this rather than polling the endpoint, and use the endpoint only to reconcile after an outage.

Invoice Payment Returned

An ACH payment can be returned by the customer’s bank days after it was made, for example for insufficient funds or a closed account. When that happens to a payment on an invoice, the invoice is reopened before this event is sent: the payment is taken off it, and status, amount_paid and balance show what is owed now. The status goes back to partially_paid if other payments still stand, otherwise to viewed or sent. The customer is emailed a link to pay again. The payload is the invoice, with a returned_payment block added:

{
  "company_sid": "000010",
  "type": "invoice_payment_returned",
  "id": 4021,
  "invoice_number": "INV-0007",
  "status": "sent",
  "amount_paid": 0.0,
  "balance": 250.0,
  "returned_payment": {
    "amount": 250.0,
    "transaction_info_id": "9876543210",
    "return_code": "R01",
    "return_reason": "Insufficient Funds",
    "returned_at": "2026-07-20T07:40:00+00:00"
  }
}

(The rest of the invoice fields are shown above and are left out here.) Returns come in with the nightly bank-return file, usually two to five banking days after the payment, so expect this event the morning after a return rather than in real time. The same return also sends ACH Payment Return. That older event doesn’t say which invoice it belongs to, so build against this one.

If your system treats Invoice Paid as final, handle this event too: a paid invoice can become unpaid again. Void and refunded invoices are never reopened.

Subscription Payment Failed

This event fires in two cases. failure_source tells them apart:

charge: the renewal charge was declined.
ach_return: an ACH payment had gone through (a renewal, or the subscription’s first payment), and the customer’s bank returned it days later, for example for insufficient funds or a closed account. The payload adds a returned_payment block, the same shape as on Invoice Payment Returned.

{
  "company_sid": "000010",
  "type": "subscription_payment_failed",
  "subscription_id": 88,
  "subscription_plan_id": 12,
  "plan_name": "Monthly Membership",
  "status": "Active",
  "payment_method_id": 5021,
  "customer_uuid": "9f2a6c14-3e8b-4d21-9a77-5c1e0b8f4d33",
  "amount": 49.99,
  "next_run_date": "2026-10-04",
  "transaction_error_code": "R01",
  "transaction_error": "Insufficient Funds",
  "failed_count": 1,
  "failure_source": "ach_return",
  "returned_payment": {
    "amount": 49.99,
    "transaction_info_id": "9876543210",
    "return_code": "R01",
    "return_reason": "Insufficient Funds",
    "returned_at": "2026-10-02T07:40:00+00:00"
  }
}

A returned payment is handled like a declined renewal, and the subscription has already been updated when the event is sent:

Insufficient funds: the payment is retried the next day, and counts toward the three failed attempts after which the subscription’s status becomes Failed.
Closed or invalid account: the subscription is Failed at once. The customer is emailed a link to update their bank details.
Payment stopped or authorization revoked: the subscription is Cancelled, and Subscription Cancelled is also sent.

The customer still owes the returned period; the retry collects it. If the subscription was already paused, cancelled, ended or failed, it’s left as it is, but the event is still sent.

If your system treats Subscription Renewed as final, handle this event too: a renewal that succeeded can be returned by the bank two to five banking days later. Payloads sent before failure_source existed are always declined charges.

Held funds releases

Funds Released, Funds Release Failed and Funds Release Unconfirmed carry the release exactly as POST /api/funds/release returns it, plus company_sid and type. You can reconcile the webhook and the API response the same way.

{
  "company_sid": "91828382",
  "type": "funds_release_failed",
  "id": 512,
  "amount": 1500.0,
  "fee": 30.0,
  "status": "failed",
  "status_label": "Failed",
  "idempotency_key": "payout-2026-09-25-0001",
  "transaction_info_ids": null,
  "failure_reason": "The processor declined the transfer (code 66).",
  "requested_at": "2026-09-25T14:02:11+00:00",
  "completed_at": "2026-09-25T14:02:14+00:00"
}

`type`	`status`	Meaning
`funds_released`	`released`	Sent. `failure_reason` is `null`
`funds_release_failed`	`failed`	Declined, nothing moved. `failure_reason` says why
`funds_release_unconfirmed`	`unknown`	No confirmation came back, so the money may have gone. `completed_at` is `null`

transaction_info_ids lists the payments released when the release named payments, and is null when it named an amount. Match on idempotency_key or id to find the release in your own records. Treat funds_release_unconfirmed as neither sent nor failed. Its amount is held back from releasable until it is reconciled, so it can’t be paid out twice. Don’t mark it failed in your ledger. Check the balance later to see how it resolved. A retry with the same idempotency_key returns the original release and sends no new webhook. When the merchant belongs to an affiliate, the affiliate’s endpoints for these events receive them too. company_sid tells the merchants apart.

For the payloads that carry no type, identify the event from the endpoint URL that received it (see One endpoint per event above).

Verifying webhook signatures

Dime Payments signs every delivery with the secret shown for that endpoint in the dashboard. Each request carries three headers:

Header	Value
`X-Dime-Timestamp`	When this attempt was sent, in Unix seconds
`X-Dime-Signature`	`sha256=` followed by a hex HMAC-SHA256 of `{timestamp}.{raw body}`
`Signature`	A hex HMAC-SHA256 of the raw body alone. Kept for existing integrations

Verify X-Dime-Signature. The timestamp is part of what is signed, so it can’t be changed without breaking the signature. Rejecting old timestamps stops anyone who captures a delivery from replaying it to you later.

$body      = file_get_contents('php://input'); // the raw bytes, before any JSON parsing
$timestamp = $_SERVER['HTTP_X_DIME_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_DIME_SIGNATURE'] ?? '';
$secret    = 'your-webhook-secret';

if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401); // too old, or too far in the future
    exit;
}

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Sign the raw body, not a re-encoding of the parsed JSON. Re-encoding can reorder keys and reformat numbers, which causes mismatches that look random.
Compare with a timing-safe function such as hash_equals, never ==.
Five minutes (300 seconds) is a sensible tolerance. Choose your own, but allow for clock differences in both directions.
The timestamp is when that attempt was sent, not when the event happened. Every retry is signed again with a fresh timestamp, so a retry hours later still passes your tolerance. That also means the timestamp can’t tell you about duplicates: a retry of an event you already handled looks new. Deduplicate on an id in the payload, such as a transaction, invoice, chargeback or release id.

Signature still works exactly as before, so an integration that already checks it keeps working. It proves the delivery came from us and wasn’t changed, but not when it was sent, so a captured delivery would still verify later. Move to X-Dime-Signature when you can.

Retries

Any response other than a 2xx within 15 seconds counts as a failure. A failed delivery is retried with exponential backoff, up to 5 attempts spread over about three hours (retries after about 10 seconds, 100 seconds, 17 minutes and 3 hours), before it is abandoned. Because a delivery can arrive more than once, make your handler safe to run twice.

After 3 events in a row fail every attempt, the endpoint is disabled and its owner is emailed. Nothing is sent to it until someone turns it back on from the Webhooks screen. Events that happen while it is disabled are not queued and can’t be resent.

There is no delivery-history screen and no manual resend, so treat webhooks as best-effort rather than a guaranteed ledger. Reconcile against the API for anything you can’t afford to miss.

Testing webhooks locally

Use a tool like ngrok to expose your local server to the internet during development:

ngrok http 3000

Use the generated https:// URL as your webhook endpoint in the dashboard.

Next steps

Disputes — understand how chargebacks work
Held Funds — release held money and track the result
Payouts — understand how funds are deposited
API Reference — full endpoint documentation

Getting Started

SDKs

Payments

Going Live

Integrations

Reference

Overview

Setting up a webhook

One endpoint per event

Event types

Onboarding

Credit card

Chargebacks

Risk retrievals

ACH

Recurring payments

Invoicing

Subscriptions

Held funds

Payload format

Application Status Changed

Invoice Payment Returned

Subscription Payment Failed

Held funds releases

Verifying webhook signatures

Retries

Testing webhooks locally

Next steps

​Overview

​Setting up a webhook

​One endpoint per event

​Event types

​Onboarding

​Credit card

​Chargebacks

​Risk retrievals

​ACH

​Recurring payments

​Invoicing

​Subscriptions

​Held funds

​Payload format

​Application Status Changed

​Invoice Payment Returned

​Subscription Payment Failed

​Held funds releases

​Verifying webhook signatures

​Retries

​Testing webhooks locally

​Next steps

Overview

Setting up a webhook

One endpoint per event

Event types

Onboarding

Credit card

Chargebacks

Risk retrievals

ACH

Recurring payments

Invoicing

Subscriptions

Held funds

Payload format

Application Status Changed

Invoice Payment Returned

Subscription Payment Failed

Held funds releases

Verifying webhook signatures

Retries

Testing webhooks locally

Next steps