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

# Webhooks

> Get notified on every Payment Intent state transition

Webhooks fire on every state transition, delivering real-time updates to your server. Configure your webhook URL in the [dashboard](https://dashboard.crycketpay.com).

## Event format

Every webhook delivery has the same envelope:

```json theme={null}
{
  "eventId": "evt_abc123",
  "type": "intent.confirmed",
  "createdAt": "2026-04-06T12:00:00Z",
  "livemode": true,
  "data": {
    "intent": { /* full PaymentIntent object */ }
  }
}
```

## Event types

| Event                   | Trigger                                     |
| ----------------------- | ------------------------------------------- |
| `intent.created`        | Intent created                              |
| `intent.pending`        | Transaction broadcast to chain              |
| `intent.confirmed`      | Sufficient confirmations                    |
| `intent.finalized`      | Chain-level finality                        |
| `intent.failed`         | On-chain failure (revert, program error)    |
| `intent.expired`        | TTL elapsed without fulfillment             |
| `intent.cancelled`      | Explicitly cancelled                        |
| `intent.retry_required` | Transaction dropped, fulfiller must re-sign |
| `intent.detected`       | Fulfiller acknowledged audio receipt        |

## Verifying signatures

Every delivery includes an `X-PF-Signature` header signed with your webhook secret using HMAC-SHA256 (same pattern as Stripe):

```javascript theme={null}
import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

Your webhook secret is available in the [dashboard](https://dashboard.crycketpay.com).

## Delivery guarantees

* **Retry policy:** Exponential backoff, \~10 attempts over up to 72 hours
* **Ordering:** Best-effort. Events may arrive out of order — always confirm current state via `GET /v1/intents/:id` before acting
* **Deduplication:** Each event has a stable `eventId`. The same event may be delivered more than once — deduplicate on `eventId`

## Managing deliveries

List recent deliveries and retry failed ones via the API:

```bash theme={null}
# List recent deliveries
curl https://api.crycketpay.com/v1/webhooks \
  -H "Authorization: Bearer pk_live_..."

# Retry a failed delivery
curl -X POST https://api.crycketpay.com/v1/webhooks/del_abc123/retry \
  -H "Authorization: Bearer pk_live_..."
```