> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runpayments.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server.

# Webhooks Overview

Webhooks provide real-time notifications about events within the Run Developer ecosystem. They allow your application to receive instant updates when boarding merchants and running transactions.

## How Webhooks Work

When an event occurs in the Run Payments system, we send an HTTP POST request to the configured webhook endpoints. These requests contain detailed information about the event, allowing your application to respond immediately.

## Event Types

Run Payments sends webhooks for the following events:

### Merchant Boarding Status Events

* `merchant.new` - New merchant created
* `merchant.sent_for_signature` - Documents sent for signature
* `merchant.signed` - Documents signed
* `merchant.in_underwriting` - Application in underwriting
* `merchant.boarded` - Merchant successfully boarded
* `merchant.live` - Merchant account is live
* `merchant.cancelled` - Application cancelled
* `merchant.declined` - Application declined
* `boarding.varcomplete` - VAR Information Completed

### Transaction Reporting Events (Guide coming soon)

* `transaction.entered` - New transaction entered
* `transaction.decline` - Transaction declined
* `transaction.refund` - Transaction fully refunded
* `transaction.partialrefund` - Transaction partially refunded
* `transaction.reject` - Transaction rejected
* `chargeback.entered` - New chargeback reported
* `funding.entered` - New funding information available
* `statement.entered` - New statement available for download

## Webhook Structure

All webhooks follow a consistent structure:

```json
{
  "event_type": "transaction.entered",
  "source_id": 12345,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "payload": {
    // Event-specific data
  },
  "metadata": {
    "webhook_id": "wh_abc123def456",
    "attempt": 1,
    "idempotency_key": "transaction-entered-12345-20240115103000"
  }
}
```

### Security Headers

Every webhook request also includes security headers:

* `Content-Type: application/json`
* `X-Webhook-Signature-256: sha256=<hmac_signature>`
* `X-Idempotency-Key: <unique_key>`

### Retry Policy

Failed webhook deliveries are automatically retried according to this schedule:

| Attempt | Delay      | Total Time Since First |
| ------- | ---------- | ---------------------- |
| 1       | Immediate  | 0 seconds              |
| 2       | 5 seconds  | 5 seconds              |
| 3       | 5 minutes  | 5 minutes 5 seconds    |
| 4       | 30 minutes | 35 minutes 5 seconds   |
| 5       | 2 hours    | 2 hours 35 minutes     |
| 6       | 5 hours    | 7 hours 35 minutes     |
| 7       | 10 hours   | 17 hours 35 minutes    |
| 8       | 10 hours   | 27 hours 35 minutes    |

**Maximum Attempts:** 8 total (1 initial + 7 retries)

## Getting Started

1. **Configure Endpoints**: Share webhook endpoints with your Integration Delivery lead.
2. **Implement Handlers**: Create endpoint handlers in your application.
3. **Verify Signatures**: Always verify webhook signatures for security.
4. **Handle Idempotency**: Use the idempotency key to prevent duplicate processing.
5. **Test Thoroughly**: Test all event types and error scenarios.