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

# Test webhooks locally

> Receive Tirdad webhooks on a laptop with a tunnel or Svix Play, trigger real events through the API, and replay deliveries

Tirdad needs a public HTTPS URL to deliver to, and your handler runs on `localhost`. Bridge the gap with a tunnel, or skip your handler entirely and inspect payloads in a browser. Then trigger events through the API so you are testing real deliveries, not hand-written fixtures.

## Option 1: Inspect payloads with Svix Play

For a first look at what an event contains, you do not need any code:

1. Open [play.svix.com](https://play.svix.com) and copy the URL it gives you (it looks like `https://play.svix.com/in/e_...`).
2. Register that URL as an endpoint in the dashboard under **Developers > Webhooks**.
3. Trigger an event (see below). The payload, headers, and signature appear in the browser.

Delete the endpoint when you are done; the Play URL is public to anyone who has it.

## Option 2: Tunnel webhooks to your local handler

Run your handler locally and expose it:

```sh ngrok theme={null}
ngrok http 3000
# Forwarding  https://a1b2c3.ngrok-free.app -> http://localhost:3000
```

```sh Cloudflare Tunnel theme={null}
cloudflared tunnel --url http://localhost:3000
# https://random-words.trycloudflare.com
```

Register the tunnel URL plus your route (for example `https://a1b2c3.ngrok-free.app/webhooks/tirdad`) as a sandbox endpoint, and copy its signing secret into your local environment as `TIRDAD_WEBHOOK_SECRET`. Free tunnels change their hostname on every restart, so update the endpoint URL in the dashboard when that happens, or use a reserved domain.

> [!NOTE]
>
> ngrok's local inspector at `http://127.0.0.1:4040` shows every request and lets you replay it against your handler without going back to Tirdad.

## Triggering real webhook events

Use a sandbox API key and the API to cause the events you want to test:

| To fire | Call |
| - | - |
| `customer.created` | [`POST /customers`](https://docs.tirdad.ai/api-reference/customers/create-customer) |
| `subscription.created` | [`POST /subscriptions`](https://docs.tirdad.ai/api-reference/subscriptions/create-subscription) |
| `wallet.created`, `wallet.transaction.created` | [`POST /wallets`](https://docs.tirdad.ai/api-reference/wallets/create-a-new-wallet), then [`POST /wallets/{id}/top-up`](https://docs.tirdad.ai/api-reference/wallets/top-up-wallet) |
| `invoice.update.finalized` | [`POST /invoices/{id}/finalize`](https://docs.tirdad.ai/api-reference/invoices/finalize-invoice) on a draft invoice |
| `invoice.communication.triggered` | [`POST /invoices/{id}/comms/trigger`](https://docs.tirdad.ai/api-reference/invoices/trigger-invoice-communication-webhook) |
| `subscription.cancelled` | [`POST /subscriptions/{id}/cancel`](https://docs.tirdad.ai/api-reference/subscriptions/cancel-subscription) |
| `event.rejected` | [`POST /events`](https://docs.tirdad.ai/api-reference/events/ingest-event) with an `event_name` no feature meters |

The same actions in the dashboard fire the same events.

## Replaying a webhook delivery

Every attempt is stored. In the dashboard, open the endpoint, go to **Logs**, pick a delivery, and choose resend. This is the fastest loop when iterating on a handler: fix the code, replay the same message, repeat. The replay carries the original `svix-id`, so a dedupe check keyed on it will skip the replay; clear that entry or key on something else while testing.

## Testing the signature check

A handler that verifies signatures should reject a tampered body. With the secret in hand you can produce a valid signature for any payload and confirm both paths:

```sh theme={null}
SECRET="whsec_..."           # from the endpoint page
ID="msg_test_1"
TS=$(date +%s)
BODY='{"event_type":"customer.created","customer":{"id":"cust_test"}}'

SIG=$(printf '%s.%s.%s' "$ID" "$TS" "$BODY" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$(echo -n "${SECRET#whsec_}" | base64 -d | xxd -p -c 256)" -binary \
  | base64)

curl -X POST http://localhost:3000/webhooks/tirdad \
  -H "Content-Type: application/json" \
  -H "svix-id: $ID" -H "svix-timestamp: $TS" -H "svix-signature: v1,$SIG" \
  -d "$BODY"
```

Expect `200`. Change one character in `$BODY` after computing `$SIG` and expect `400`.

## Checking the webhook handler end to end

* [ ] A valid delivery returns `200` in under a second
* [ ] A tampered body returns `400`
* [ ] Replaying the same delivery does not duplicate a side effect
* [ ] An event type you do not handle still returns `200`
* [ ] The dashboard **Logs** tab shows the attempt as successful

> [card] [Event catalog](https://docs.tirdad.ai/developers/webhooks/event-catalog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.