Audio is played by ElevenLabs, which loads only when you press the button. Privacy Policy

Webhooks

A webhook sends an event from Booked55 to another system the moment something happens, so a tool such as Zapier, Make or n8n can act on it. Booked55 sends its own payload format; the receiving tool maps it onto whatever it needs.

Who can use webhooks

Owners and managers. Webhooks also have to be turned on for your organization: until they are, the Webhooks page doesn't appear in the sidebar. Booked55 support turns the feature on. If it is turned off later, new events stop being sent too.

Creating an endpoint

  1. 1

    Open Webhooks

    In the sidebar, go to Workspace → Workspace Settings → Integrations → Webhooks (outbound).

  2. 2

    Click "Add endpoint"

    The Add endpoint window opens.

  3. 3

    Enter the Endpoint URL

    The address that should receive events, for example a Zapier "Catch Hook" URL. It must start with https://. Addresses that point at private or internal networks are refused.

  4. 4

    Add a Label

    Say what the endpoint is for, such as "Zapier → JobAdder". It is the easiest way to tell endpoints apart later.

  5. 5

    Choose the Events

    Tick the events this endpoint should receive. The Events section below lists them.

  6. 6

    Click "Create endpoint" and copy the signing secret

    The Signing secret window shows the secret once. Copy it into the receiving system before you close the window. It can’t be shown again, only regenerated.

Events

EventWhen it fires
deal.createdA deal is created: by hand, when a pipeline card enters a Client stage, from a CSV import, or through the API.
deal.cancelledA deal is cancelled, which stops its schedule of payments.
pipeline_item.createdA card is added to a pipeline. Its first stage is in new_stage_name, and the old_ fields are null.
pipeline_item.stage_changedA card moves to another stage in the same pipeline.
pipeline_item.pipeline_changedA card moves to another pipeline. A stage belongs to one pipeline, so its stage changes too, and only this event fires.
invoice.createdAn invoice is made for a payment on a deal.
invoice.sentAn invoice is marked Sent. Marking a Draft Paid fires this and then invoice.paid.
invoice.paidAn invoice is marked Paid.
invoice.cancelledAn invoice is cancelled.
invoice.voidedAn invoice is voided. A corrected copy of it arrives as invoice.created.
invoice.refundedMoney from a paid invoice is given back.
invoice.refund_demandedA refund is asked for on a paid invoice.
invoice.refund_demand_droppedA refund demand is dropped, so the invoice is Paid again.
invoice.payment_undoneA payment is undone, so a Paid invoice is Sent again.
invoice.editedA correction to a migrated invoice changes its status.

The card events fire for every move: a drag on the board, a bulk move, stage automation and a move through the API. They carry the same deal, contact and company as deal.created, with deal set to the card's newest deal or null when it has none, and add pipeline_item:

"pipeline_item": {
  "id": "...",
  "value": 12500,
  "assigned_to": "...",
  "assigned_to_user": { ... },
  "old_pipeline_id": "...",
  "old_pipeline_name": "Sales",
  "old_stage_id": "...",
  "old_stage_name": "Qualified Lead",
  "new_pipeline_id": "...",
  "new_pipeline_name": "Sales",
  "new_stage_id": "...",
  "new_stage_name": "Proposal",
  "moved_at": "2026-08-13T14:02:11.402Z"
}

The invoice events carry the same deal, contact and company, with deal set to null if the deal has since been deleted, and add invoice as it stood at that moment:

"invoice": {
  "id": "...",
  "number": "INV-00042",
  "payment_label": "Payment 3 of 12",
  "due_date": "2026-03-15",
  "amount": 1000,
  "tax": 130,
  "total": 1130,
  "currency": "USD",
  "status": "paid",
  "paid_at": "2026-03-16",
  "pdf_url": "https://example.com/invoices/INV-00042.pdf"
}

number is null on an invoice with no number. pdf_url is a link to the invoice PDF when one exists, and null when none does. The link works for one hour. Booked55 makes the PDF before the event goes out, so invoice.sent can carry its link.

deal.cancelled carries the same deal, contact and company as deal.created.

A deal's value is the amount of one payment. booked_value is what the deal is worth when it closes. See What a deal's numbers mean.

A deal's note also arrives as description, its old name. Read note; both names keep arriving.

What a delivery contains only ever grows. Booked55 may add a field or an event type at any time, and never renames, removes or changes the meaning of one that is already sent, so what you build on a field today keeps working.

Booked55 starts recording events for an organization once an endpoint subscribes to them. Deals created before that are not sent.

What a delivery contains

Each delivery is an HTTPS POST with a JSON body. The deal, its contact and its company are included in full, so the receiving tool doesn't need to look anything up. A field with no value is sent as null rather than left out. A shortened example:

{ "id": "evt_a1b2c3...", "type": "deal.created", "created_at": "2026-08-13T14:02:11.402Z", "account_id": "6a7e...", "actor": { "type": "user", "id": "6a7e...", "name": "Sam Lee" }, "test": false, "data": { "deal": { "id": "...", "value": 1000, "booked_value": 12000, "schedule_text": "...", "status": "active", "note": "...", "client_type": { ... }, "assigned_to_user": { ... } }, "contact": { "id": "...", "name": "...", "email": "...", "phone_numbers": [ ... ] }, "company": { "id": "...", "name": "...", "domain": "acme.com", "website": "..." } } }

id is unique per event: use it to ignore a delivery you have already handled. test is true for test events, so they never create real records on your side.

Every request also carries these headers:

HeaderValue
Booked55-Signaturet=<timestamp>,v1=<signature>, see below
Booked55-TimestampWhen the request was signed, in Unix seconds
Booked55-Event-IdThe event's id
Booked55-Event-TypeFor example deal.created
Booked55-Delivery-IdThis delivery
Booked55-AttemptThe attempt number, starting at 1

Verifying the signature

Check the signature before trusting a request, so nobody else can send fake events to your endpoint. Booked55 signs each request with the endpoint's signing secret (it starts with whsec_):

  1. Read t and v1 from the Booked55-Signature header.
  2. Refuse the request if t is more than 5 minutes away from your current time.
  3. Compute HMAC-SHA256 of <t>.<raw request body>, using the whole secret, whsec_ included, as the key. Write the result as lowercase hex.
  4. Compare it with v1 using a constant-time comparison. Accept the request only if they match.

Node.js:

const crypto = require('crypto') // rawBody must be the exact bytes Booked55 sent, before any JSON parsing. function isFromBooked55(secret, rawBody, signatureHeader, toleranceSeconds = 300) { const parts = Object.fromEntries( signatureHeader.split(',').map((piece) => piece.trim().split('=')) ) const timestamp = Number(parts.t) if (!timestamp || !parts.v1) return false // Refuse old deliveries so a captured request can't be replayed later. if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false const expected = crypto .createHmac('sha256', secret) .update(`${timestamp}.${rawBody}`) .digest('hex') const expectedBytes = Buffer.from(expected, 'hex') const receivedBytes = Buffer.from(parts.v1, 'hex') return expectedBytes.length === receivedBytes.length && crypto.timingSafeEqual(expectedBytes, receivedBytes) }

Python:

import hashlib, hmac, time def is_from_booked55(secret: str, raw_body: bytes, signature_header: str, tolerance_seconds: int = 300) -> bool: parts = dict(piece.strip().split("=", 1) for piece in signature_header.split(",")) timestamp = int(parts.get("t", "0")) received = parts.get("v1", "") if not timestamp or not received: return False if abs(time.time() - timestamp) > tolerance_seconds: return False signed = f"{timestamp}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, received)

Deliveries, retries and redelivery

Click an endpoint to open its page. It shows the endpoint's status, its events, a preview of the secret, the last successful delivery, and Delivery history, which you can filter by outcome (Delivered, Failed, Retrying, Pending, Skipped) and by event.

  • Delivered — Your endpoint answered with a 2xx status.
  • Retrying — Your endpoint didn't answer within 10 seconds, couldn't be reached, or answered with a status that is worth retrying: 5xx, 408, 429, or a redirect (redirects are never followed). Booked55 tries again with growing gaps (about 1 minute, then 2, 4, 8 and so on, up to every 4 hours), at most 14 attempts within 24 hours.
  • Failed — Your endpoint answered with a 4xx status other than 408 or 429, or the retries ran out. A 4xx is not retried, because sending the same request again won't change the answer.
  • Skipped — The endpoint was disabled when the event happened, or your organization had no active subscription when the delivery was due. Events that happen while there is no active subscription are not sent at all; see When there is no active subscription.

Click a delivery to see the full request, headers and your endpoint's response. Click Redeliver there to send the same event again. Redeliver adds a new row, marked Manual, and keeps the original. It needs the endpoint to be active, and it sends to the endpoint's current URL.

Request and response bodies are kept for 7 days, delivery rows for 30 days, and events for 90 days. After 90 days an event can no longer be redelivered.

Send test event

On the endpoint page, Send test event sends sample data (not a real deal) with "test": true. It is tried once, with no retries, and the result appears straight away. Test events don't count toward auto-disable. A test of an invoice.* event carries a sample invoice as well.

Auto-disable

After 10 deliveries in a row fail, Booked55 disables the endpoint, shows it as Auto-disabled with the reason, and sends the organization's owners a notification in Booked55. Fix the receiving side, then click Edit, tick Active and save. Re-enabling also clears the failure count. Events that happen while an endpoint is disabled are recorded as Skipped.

Editing, secrets and deleting

  • Edit — Change the URL, Label, Events or Active. Changing the URL sends every future event to the new address.
  • Regenerate secret — On the endpoint page. The new secret is shown once, and every request after that is signed with it, so your receiver rejects them until you update it there.
  • Delete — The trash icon on the Webhooks page. Nothing more is delivered to that URL.

Webhooks and the AI assistant

The AI assistant can list endpoints and deliveries, and it can create, edit, test, redeliver and delete endpoints. Each of those actions waits on a confirmation card, and nothing happens until you click Confirm. When you create an endpoint or change its URL, the card leads with the destination address and the warning “Booked55 will send contact and company details to this address on every event this endpoint listens for.” After you confirm a new endpoint, the card shows the signing secret once. The assistant itself never sees the secret, and it can't regenerate one; use Regenerate secret on the endpoint page.

Ready to get started?

Create your free Booked55 account and start managing your sales pipeline in minutes.