> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimepayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time notifications when events occur in your Dime Payments account.

## Overview

Webhooks allow your application to receive real-time notifications when events occur -- a transaction succeeds, a recurring payment fails, a dispute is opened. Instead of polling the API, Dime Payments pushes event data to a URL you specify.

## Setting up a webhook

1. Log into the [Dime Payments dashboard](https://app.dimepayments.com)
2. Navigate to **Settings > Webhooks**
3. Click **Add Endpoint**
4. Enter your publicly accessible HTTPS URL
5. Select the events you want to receive
6. Save

Your endpoint must return a `200` HTTP response within 30 seconds or the delivery will be marked as failed and retried.

## Event types

| Event                         | When it fires                                   |
| ----------------------------- | ----------------------------------------------- |
| `transaction.success`         | A charge completes successfully                 |
| `transaction.failed`          | A charge is declined or fails                   |
| `transaction.refunded`        | A refund is processed                           |
| `transaction.voided`          | A transaction is voided                         |
| `recurring_payment.success`   | A scheduled recurring payment runs successfully |
| `recurring_payment.failed`    | A scheduled recurring payment fails             |
| `recurring_payment.cancelled` | A recurring payment is cancelled                |
| `dispute.opened`              | A chargeback or dispute is filed                |
| `dispute.resolved`            | A dispute is resolved                           |

## Payload format

All webhook payloads are JSON and follow the same envelope structure:

```json theme={null}
{
  "event": "transaction.success",
  "data": {
    "transaction_type": "CC",
    "transaction_status": "Success",
    "transaction_number": "1234567890",
    "transaction_date": "2026-01-01T00:00:00.000000Z",
    "amount": "49.99",
    "customer_uuid": "66f1c230-1337-5g59-b43c-1bcb83adfaaa",
    "transaction_info_id": "9876543210"
  }
}
```

## Verifying webhook signatures

Dime Payments signs every webhook payload so you can verify it came from us. A signature is included in the `X-Dime-Signature` header.

```php theme={null}
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_DIME_SIGNATURE'];
$secret    = 'your-webhook-secret';

$expected = hash_hmac('sha256', $payload, $secret);

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

## Retries

If your endpoint fails to return a `200` response, Dime Payments will retry the delivery with exponential backoff:

| Attempt | Delay      |
| ------- | ---------- |
| 1       | Immediate  |
| 2       | 5 minutes  |
| 3       | 30 minutes |
| 4       | 2 hours    |
| 5       | 8 hours    |

After 5 failed attempts the delivery is abandoned. You can view failed deliveries and manually retry them from the dashboard.

## Testing webhooks locally

Use a tool like [ngrok](https://ngrok.com) to expose your local server to the internet during development:

```bash theme={null}
ngrok http 3000
```

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

## Next steps

* [Disputes](/guides/disputes) — understand how chargebacks work
* [Payouts](/guides/payouts) — understand how funds are deposited
* [API Reference](/api-reference) — full endpoint documentation