Webhooks

Get a signed HTTPS POST when something happens, and verify that it came from Venued.

Adding an endpoint

In Studio: open Business Settings, then Webhooks. Enter the Payload URL, pick the Events, and click Add endpoint. This needs the Owner or Manager role on the business. Studio offers every event type below to every kind of business, organiser, venue or professional: the endpoint belongs to the business account, which hears both sides of its enquiries and bookings. Test queues a sample delivery whose data is only {"test": true, "message": …}.

With an API key holding webhooks:write: POST/v1/webhooks adds an endpoint, GET/v1/webhooks lists them, PATCH/v1/webhooks/{webhookId} changes url, events, description or enabled, and DELETE/v1/webhooks/{webhookId}removes one. An endpoint created this way belongs to the key’s account: an organiser, a venue or a professional.

Each account can have up to 10 endpoints.

Events

  • order.confirmed: an order moved to confirmed, paid or free. Organiser endpoints only. data: orderId, eventId, totalAmount, currency, isRsvp, quantity, billingName, billingEmail, paymentProvider.
  • event.published: an event became public, sent once. Goes to the event’s organiser and to the venue it takes place at. data: eventId, title, startTime, endTime, url.
  • enquiry.received: an enquiry reached a venue or a professional. Sent once, when it leaves draft. Goes to the venue or professional and to the business account that runs it.
  • enquiry.sent: your business sent an enquiry. The asking side of the same moment. Business accounts (organiser keys) only.
  • enquiry.quoted, enquiry.countered: a new offer from the business, or a counter-offer from the organiser.
  • enquiry.accepted, enquiry.declined, enquiry.withdrawn: the enquiry was accepted, declined by the business, or withdrawn by the organiser. A withdrawn draft sends nothing.
  • booking.confirmed: a booking was agreed, sent once. booking.cancelled: a booking was cancelled. Both go to the organiser that booked, the business booked, and its venue or professional. data: bookingId, side, state, supplier, locationId, eventId, startAt, endAt, serviceDate, dates.
  • invoice.issued: your business issued an invoice, advance invoice, final invoice or cancellation. Business accounts only. data: number, kind, issuedOn, dueOn, enquiryId, the totals and amountDueMinor. Never the buyer.

Every enquiry event goes to both sides of the deal that exist, except enquiry.received (the business) and enquiry.sent (the organiser). data: enquiryId, side (organiser or supplier), state, role, headcount, dates, acceptedDate, quote; plus locationId for the business, and eventId and supplier for the organiser. One business on both sides gets one of each.

A venue key may subscribe to event.published and the business side of its enquiries and bookings; a professional key to the same without event.published. enquiry.sent, invoice.issued and order.confirmed need an organiser key, which every kind of business can create. Asking for another type is refused.

What a delivery looks like

A JSON body: id (unique per delivery), type, createdAt (ISO 8601), principal ({type, id} of the account it is for) and data. Headers: Venued-Signature, Venued-Event (the type) and Venued-Delivery (the id).

Deliveries can arrive more than once. De-duplicate on id; a resend keeps the original id.

Verifying the signature

Venued-Signature looks like t=1727600000,v1=5f2b…. Compute HMAC-SHA256 of `${t}.${rawBody}`with the endpoint’s signing secret (whsec_…), hex-encoded, and compare it with v1 in constant time. Reject a mismatch, and reject an old t to stop replays.

The signing secret is shown beside the endpoint in Studio, and returned by the API.

Rotating the secret

In Studio, click Roll secret. The old secret keeps signing for one hour. With the API, POST/v1/webhooks/{webhookId}/rotate_secret takes grace_seconds: default 3600, at most 604800 (7 days), 0 to switch at once. It needs an Idempotency-Key header.

During the overlap, the header carries one v1 per active secret, newest first: t=…,v1=<new>,v1=<old>. Only one previous secret is kept, so rotating again during an overlap ends the older one at once.

Acknowledging and retries

Return any 2xx within 10 seconds. Anything else, a timeout or a network error counts as a failed attempt and is retried with backoff.

After 20 failed attempts in a row, retries included, the endpoint is disabled. Fix the receiver, then click Enable in Studio, or send {"enabled": true} to PATCH/v1/webhooks/{webhookId}. This resets the failure count.

The delivery log and resending

Every delivery is logged for 30 days: event type, status code, attempts, time and the exact body. In Studio, open Deliveries under the endpoint and click Send again. With the API, GET/v1/webhooks/{webhookId}/deliveries lists them newest first and POST/v1/webhooks/{webhookId}/deliveries/{deliveryId}/resend sends one again, unchanged and with the same id.

A disabled endpoint refuses a resend (409 webhook_disabled). Enable it first.