Skip to main content
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.

​
How they will work

  1. You register an HTTPS endpoint of your own and choose which events 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, records the event, and answers 2xx quickly.
  4. If your endpoint does not answer 2xx, the delivery is retried 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 will list them when they exist.

Event catalog

Every planned event type.

Signature verification

Check that a delivery came from Bullionwale.

Retries and dead-lettering

What happens when your endpoint is down.

Troubleshooting

Common delivery problems.