# Webhooks

> Event names, signature verification, retries, idempotency and the delivery log.

_Updated 2026-10-30_

## Setup

Create an endpoint in Dashboard -> Developers. The URL must be public HTTPS. Private, loopback and reserved addresses are refused at save time and again at delivery.

The signing secret is shown once when the endpoint is created. Store it like a password; it is not shown again.

## Events

- order.created, order.paid, order.updated
- payment.confirmed, payment.rejected
- payment.paid, payment.failed (legacy names kept for existing integrations)
- payment_link.created
- customer.created
- fulfillment.created, fulfillment.shipped, fulfillment.delivered

Subscribe to specific events or to * for all of them.

## Payload and signature

Every delivery is a JSON object with id, type, created_at and data. Retries reuse the same body and the same id.

The X-ToroPay-Signature header is the hex HMAC-SHA256 of the raw request body using your endpoint secret. The X-ToroPay-Event header repeats the event type.

```http
X-ToroPay-Event: payment.confirmed
X-ToroPay-Signature: <hex hmac-sha256>

{ "id": "evt_...", "type": "payment.confirmed", "created_at": "...", "data": { ... } }
```

Verify the signature against the raw body before parsing it. Compare in constant time.

## Retries and idempotency

A failed delivery is retried after 1, 5, 30, 120, 360 and 1440 minutes. After the sixth attempt it is marked failed. Retries older than 48 hours are skipped.

Treat every delivery as retryable and idempotent: dedupe on the payload id. A redirect is treated as a failed delivery, so point the endpoint at the final URL.

## Delivery log

Dashboard -> Developers -> Webhook logs shows the event, response code, attempt count and the next retry time. The signing secret is never shown there.

## Security notes

- Only HTTPS endpoints are accepted.
- Redirects are not followed, which prevents a signer from being bounced to another host.
- A response body is read up to 2,000 characters and then discarded.
- Deliveries time out after 10 seconds.

---

Source: https://www.toropay.co.in/docs/webhooks