How to send new bookings to your CRM with webhooks
On this page
What do you need for a booking webhook CRM connection?
You need an HTTPS receiver, durable storage for event receipts and permission to write to the destination CRM. Plan the mapping first. A webhook is an outgoing event notification, so the receiver still needs to translate that event into the contact, activity or appointment your destination understands.
This guide uses our signed webhook contract. It doesn't establish a native CRM connector or a Zapier application; an automation product would need to accept the request, expose its raw body and support the verification and deduplication steps below.
The API and webhooks overview explains the available building blocks. Keep destination credentials in your receiver's environment and leave them out of the booking URL and guest-facing page.
Which booking events should update the CRM?
Subscribe to the lifecycle events your destination needs, with separate handling for pending requests and confirmed bookings. Status matters. A booking.requested event shouldn't mark an appointment confirmed merely because it contains a guest email and a proposed start time.
| Event | Suggested destination action |
|---|---|
booking.created | Upsert the confirmed appointment |
booking.requested | Record a pending request |
booking.approved | Change the appointment to confirmed |
booking.declined | Record the declined request |
booking.rescheduled | Update the existing appointment time |
booking.cancelled | Mark the existing appointment canceled |
booking.no_show | Record the reported attendance outcome |
These are proposed mappings, not automatic actions performed by Barq Meet. Decide what each state means in your CRM before writing the receiver, including whether a declined request should leave a contact record behind.
We send an event envelope with id, event, createdAt and data.booking. The event id deduplicates delivery; the booking's uid identifies the appointment across changes. Don't use those identifiers interchangeably.
How do you verify a signed booking webhook?
Verify BarqMeet-Signature against the exact raw request bytes before parsing or acting on the payload. Check its timestamp too. We sign timestamp + "." + raw body with HMAC-SHA256, and the receiver should reject timestamps more than five minutes away from its current clock.
Verify the raw request body
This verification function expects a raw Buffer and the original header. It is a receiver component, not a complete CRM integration:
import { createHmac, timingSafeEqual } from 'node:crypto';
import { DateTime } from 'luxon';
export function verifiedEvent(rawBody, signatureHeader) {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) throw new Error('Set WEBHOOK_SECRET');
const fields = Object.fromEntries(
(signatureHeader || '').split(',').map(part => part.trim().split('=')),
);
const { t = '', v1 = '' } = fields;
if (!/^\d+$/.test(t) || !/^[a-f0-9]{64}$/i.test(v1)) {
throw new Error('Invalid signature format');
}
if (Math.abs(DateTime.utc().toSeconds() - Number(t)) > 300) {
throw new Error('Signature timestamp rejected');
}
const expected = createHmac('sha256', secret)
.update(t + '.')
.update(rawBody)
.digest();
if (!timingSafeEqual(expected, Buffer.from(v1, 'hex'))) {
throw new Error('Signature mismatch');
}
return JSON.parse(rawBody.toString('utf8'));
}Mount an Express raw-body route before express.json() consumes its body. Validate the parsed envelope and the booking fields your mapper uses; a successful signature doesn't excuse passing unchecked values into the CRM's write operation.
We provide the full developer contract and OpenAPI document. Keep the signing secret private and save it when you create the endpoint, because the receiver needs it to validate later requests.
How do you avoid duplicate contacts on retries?
Use a unique event receipt keyed by payload.id, atomically stored with the queued work, then update appointments by booking uid. A memory-only set isn't enough. A restarted receiver must still recognize an event that was accepted before its process stopped.
Return a successful 2xx only after durable acceptance. Let the worker retry a failed CRM write, and record completion after that write succeeds; marking an event finished before the destination update can lose the update.
We retry failed deliveries with exponential backoff, up to eight attempts within 24 hours. Endpoints that keep failing for three days can be disabled, so a webhook isn't a permanent historical feed you can ignore until the end of the month.
For a worked example, five unique booking events arriving twice produce ten HTTP deliveries but five queued event jobs. If those events include one reschedule, use its booking uid to change the existing appointment instead of adding a sixth meeting row.
Contact matching is another decision. An email-based contact upsert may suit your CRM, but one contact can have several appointments, so the contact identifier shouldn't replace the appointment identifier.
How do you test bookings going to a spreadsheet or CRM?
Create the endpoint, send its built-in test and then perform a real trial booking with an inbox you control. Test the later changes too. A successful synthetic delivery proves the receiver can respond, while a real reschedule checks whether your mapping updates the right appointment. The booking-webhook definition explains the notification sent after a booking changes, instead of the request that creates the reservation.
- Enter the public HTTPS receiver URL and select the required events.
- Save the endpoint and store its signing secret privately.
- Send the built-in test and inspect the delivery response.
- Make a trial booking, including approval if the event requires it.
- Reschedule and cancel it, checking that the original destination record changes.
- Replay one accepted event in your receiver test to check deduplication.
Keep a synthetic test out of production contact creation, or mark it as a test in your receiver. The app's test button isn't evidence that a real guest booked an appointment.
| Failure | What to inspect |
|---|---|
| Signature rejected | Raw bytes, secret and receiver clock |
| Duplicate appointment rows | Event receipts and booking UID mapping |
| Pending request recorded as confirmed | Event type and booking status mapping |
| Delivery succeeds but CRM stays unchanged | Queue worker and destination API response |
Use the custom booking API guide if you're also building the guest interface. For campaign attribution before the event is sent, read booking-source tracking.
We include webhooks without a premium tier, subject to generous fair-use controls. Review the current integration scope, then set up a booking event to connect once your receiver has passed those lifecycle tests.
Steps
Define destination fields and lifecycle states
Choose how contact details, booking UID and appointment status map into the CRM. Include pending, approved, changed and canceled appointments.
Prepare a public HTTPS receiver
Preserve the raw request body for signature verification. Add durable event receipts and a queue for destination writes.
Add the webhook endpoint
In Settings, open API & webhooks and enter the receiver URL. Select the events your mapping handles and save the signing secret privately.
Verify and durably accept each event
Check the signature and timestamp, validate the envelope, then atomically enqueue each event ID once. Return 2xx only after acceptance is durable.
Test the full appointment lifecycle
Send the built-in test, then create, reschedule and cancel a trial booking. Check that repeated deliveries don't create duplicate destination records.
Frequently asked questions
Can I send the webhook straight to a CRM URL?
Only if that destination implements the required receiver contract. Most mappings still need a layer that verifies the signature, deduplicates event IDs and translates booking fields into the destination's own contact and appointment API operations. Use a receiver that verifies the signature and transforms the payload into the CRM's documented request, instead of assuming its public website or record URL accepts booking notifications as writes.
Should a request event trigger a confirmed-meeting email?
No. Keep a pending request distinct from a confirmed appointment, and let the normal booking state determine what you send. If approval is required, handle the approval event before recording the appointment as confirmed in the destination. Map requested and confirmed states deliberately, so a guest awaiting approval doesn't receive another system's message that incorrectly says the consultation has already been accepted by the host.
Does a successful delivery mean the CRM write finished?
Not necessarily. A receiver can acknowledge durable queue acceptance before its worker writes to the CRM. Track both stages so a successful HTTP response doesn't hide a failed destination update that still needs retrying. Acknowledge only after your receiver has safely accepted responsibility for the event, and monitor the separate CRM operation so a successful webhook response isn't mistaken for a completed downstream customer-record update.
Related pages
- Booking API and webhooks for your own application
Build with REST, OpenAPI and signed webhooks. Browser keys require allowed origins; server keys stay private. Default API access is 600 requests/minute.
- How to build a custom booking page with a scheduling API
Build a custom booking interface with REST and OpenAPI. Read slots, create appointments, protect API keys and handle stale times and approval states.
- How to track where your bookings come from with UTM tags
Tag booking links with utm_source, utm_medium and utm_campaign. Test attribution in Insights and distinguish campaign labels from page, embed and API.
- What is a booking webhook?
A booking webhook sends an event notification to your endpoint. Learn signed delivery, retries and duplicate handling with a one-booking example.
Create your free booking link
Sign in with Google, create an event and share your link.
Create your free link