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

# Webhooks

> Get told when your orders are booked, closed or rejected, instead of polling for them.

> [!WARNING]
>
> **Not available yet.** Webhooks are being built and are not part of the API today: there is no way to subscribe yet, and no events are sent. This page describes the planned design so you can prepare; details may change before release.

Webhooks will let Bullionwale call **your** server when something happens to your orders, so you do not have to poll `GET /orders/{order_id}`. Until they are available, poll as described in [Follow a pending order](/api-reference/orders/overview#follow-a-pending-order).

## How they will work

1. You register an HTTPS endpoint of your own and choose which [events](/webhooks/event-catalog) it receives. Bullionwale gives you a **signing secret** for it, shown once.
2. When an event happens, Bullionwale sends an HTTPS `POST` to your endpoint with a JSON body describing it.
3. Your endpoint [verifies the signature](/webhooks/signature-verification), records the event, and answers `2xx` quickly.
4. If your endpoint does not answer `2xx`, the delivery is [retried](/webhooks/retries) with a growing delay.

Each environment has its own subscriptions: test orders produce test events, production orders production events.

## Design rules to plan for

* **At least once.** An event can arrive more than once. Every event carries a unique **event id**: store the ids you have handled and ignore a repeat.
* **Not in order.** Events can arrive out of order, especially after a retry. Use the event's time and the order's `status`, not arrival order, to decide what is current.
* **Verify every delivery.** Reject any request whose signature does not verify: anyone can send a `POST` to a public URL.
* **Answer fast.** Acknowledge with `2xx` first and do slow work afterwards, so deliveries are not retried just because your handler was busy.
* **The API stays the source of truth.** A webhook tells you that something changed; read the order with the API when you need its full, current state.

Managing subscriptions will need new key scopes for reading and changing webhooks. The [Scope reference](/scopes) will list them when they exist.

> **[Event catalog](/webhooks/event-catalog)**
>
> Every planned event type.

> **[Signature verification](/webhooks/signature-verification)**
>
> Check that a delivery came from Bullionwale.

> **[Retries and dead-lettering](/webhooks/retries)**
>
> What happens when your endpoint is down.

> **[Troubleshooting](/webhooks/troubleshooting)**
>
> Common delivery problems.


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