Skip to main content
Sign every request. See Send order events and Sign your requests.

Authorizations

​
X-Bilt-Key-Id
string
header
required

Order reports are signed, not sent with a token. Send the key ID Bilt issued when you registered your Ed25519 public key in X-Bilt-Key-Id, and sign each request with the Standard Webhooks v1a scheme in the webhook-* headers. See Sign your requests.

Headers

​
webhook-id
string
required

Unique ID for this request, and the deduplication key. Send the same value with the same body on every retry. The same value with a different body is REJECTED with IDEMPOTENCY_KEY_REUSED.

Required string length: 1 - 1024
​
webhook-timestamp
string
required

When you signed the request, in integer Unix seconds. Bilt rejects a timestamp more than 300 seconds from when it received the request (stale_timestamp).

Maximum string length: 1024
Pattern: ^\d+$
​
webhook-signature
string
required

v1a, followed by the base64 Ed25519 signature of {webhook-id}.{webhook-timestamp}.{raw body}. You can send several space-separated entries during key rotation. Any one valid v1a entry passes, and other schemes are ignored.

Required string length: 1 - 1024

Body

application/json

One change to one order. An unknown key anywhere in the event makes it REJECTED with VALIDATION_FAILED.

​
idempotencyKey
string
required

Unique per event. Send the same value, with the same body, on every retry of the event.

Pattern: ^[A-Za-z0-9._:-]{1,128}$
​
orderId
string
required

Your ID for the order. The same on every event of the order.

Pattern: ^[A-Za-z0-9._:-]{1,128}$
​
partnerMemberId
string
required

Your ID for the customer. It must equal, byte for byte, the value you used when they linked. No surrounding whitespace.

Maximum string length: 256
Pattern: ^\S(.*\S)?$
​
currency
enum<string>
required

The currency of every amount in the order. The same on every event of the order.

Available options:
USD,
CAD,
GBP,
EUR
​
createdAt
string
required

When the change this event reports happened.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$
Example:

"2026-10-07T14:02:11Z"

​
order
PURCHASE · object
required

What happened to the order. type selects the variant.

​
payments
object[]

One entry per tender whose money moved in this event. Send it only when money moved. Required on PAYMENT_UPDATED.

Required array length: 1 - 10 elements

Response

Bilt stored the request and will check it within seconds. The outcome (ACCEPTED, HELD, or REJECTED, with a reason) is not in the response. No body.