> For the complete documentation index, see [llms.txt](https://docs.wandreferrals.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wandreferrals.com/integrations-and-api-production-rollout-gate-pending/outbound-webhooks.md).

# Outbound webhooks setup

## What it does

Outbound webhooks fire an HTTP `POST` to a URL you choose for the lifecycle events currently wired by the application. Use them to trigger Zapier/Make automations or push events into your own systems.

## Set one up

1. Open **Settings → Integrations → Outbound webhooks**.
2. Add a public endpoint URL that starts with `https://`. The current Settings form checks URL shape when saving; the delivery guard later refuses plain HTTP, internal, private-network, and metadata targets. An unsafe target can remain listed but will receive no delivery, so use only public HTTPS.
3. Optionally choose which **events** to receive (leave empty for all).
4. Optionally set a **secret** so each delivery is signed (recommended).
5. Toggle it on. The current **test** action emits one generic `test` event across the shop's eligible subscriptions: empty filters and filters explicitly containing `test` receive it, while filters containing only other values do not receive it. Multiple eligible subscriptions may receive it. For isolated validation, use a temporary endpoint with an empty filter or explicit `test` filter in an authorized non-production environment, then disable or remove it after confirming the signature.

## Events you can receive

The current application emits `affiliate.approved`, `affiliate.rejected`, `affiliate.status_changed`, and `commission.created`. The generic `test` event is emitted only by the test action. It is not advertised in the Settings/API event registry, but the subscription API currently accepts arbitrary filter strings, so an explicit `test` filter is stored and receives it.

The settings/API registry also accepts these reserved filter names, but no current lifecycle call site emits them: `affiliate.created`, `commission.approved`, `commission.paid`, `commission.reversed`, `payout.completed`, `payout.failed`, `registration.submitted`, `chat.message_received`, `ticket.created`, and `milestone.reached`. A subscription filtered only to reserved names receives nothing until the corresponding producer is implemented and released.

## Delivery & security

* Each delivery includes an `X-Wand-Event` header and an `X-Wand-Signature` header (an HMAC-SHA256 of the body, keyed by your secret).
* Delivery is **best-effort and non-blocking** — a failed webhook never breaks your store's core flows, and there is no automatic retry.

## For developers

Full payload format and signature-verification code samples (Node & Python) are in the developer guide: [**Outbound Webhooks & HMAC Signature Verification**](/integrations-and-api-production-rollout-gate-pending/webhooks.md). You can also manage subscriptions programmatically via `POST/GET/DELETE /api/v1/webhooks` — see the [API reference](/integrations-and-api-production-rollout-gate-pending/reference.md).

## Related

* [Integrations overview](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/overview/README.md)
* [Public API](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/public-api/README.md)