> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookingshake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time notifications when accounts, contacts, invoices, and payments change in BookingShake

## Overview

Webhooks allow your application to receive real-time notifications when data changes in BookingShake. Instead of polling the API for updates, BookingShake automatically sends HTTP POST requests to your specified endpoint whenever an account, contact, or payment is created, updated, or deleted - or when an invoice is issued.

**Why use webhooks?**

* **Real-time updates**: Receive notifications instantly when data changes
* **Reduced API usage**: No need to continuously poll for changes
* **Efficient**: Only get notified about events you care about
* **Scalable**: Build reactive integrations that sync data automatically

**Common use cases:**

* Sync contacts and accounts to external CRM systems (Salesforce, HubSpot, etc.)
* Sync invoices and payments to your accounting software or ERP
* Trigger automated workflows when new contacts are created
* Update analytics dashboards in real-time
* Maintain data consistency across multiple platforms

## Quick Start

<Steps>
  <Step title="Access Webhook Settings">
    In your BookingShake dashboard, go to **Settings > Integrations** and scroll to the **Webhooks** section.
  </Step>

  <Step title="Create a Webhook">
    Click **New Webhook** and configure:

    * **Name**: A descriptive name for your webhook (e.g., "CRM Sync")
    * **URL**: Your HTTPS endpoint (e.g., `https://api.yourdomain.com/webhooks/bookingshake`)
    * **Events**: Select which events to receive (see available events below)
  </Step>

  <Step title="Save and Copy Secret">
    After saving, copy the webhook secret. You'll need it to verify webhook signatures for security.
  </Step>

  <Step title="Test Your Webhook">
    Create or update a contact or account to trigger a test webhook delivery.
  </Step>
</Steps>

## Available Events

BookingShake supports ten webhook events:

| Event                             | Description          | Triggered When                                                            |
| --------------------------------- | -------------------- | ------------------------------------------------------------------------- |
| `account.created`                 | New account created  | A company is added to your venue                                          |
| `account.updated`                 | Account modified     | Company information is updated                                            |
| `account.deleted`                 | Account removed      | A company is deleted                                                      |
| `contact.created`                 | New contact created  | A person is added to your venue                                           |
| `contact.updated`                 | Contact modified     | Contact information is updated                                            |
| `contact.deleted`                 | Contact removed      | A contact is deleted                                                      |
| `invoice.created` <sup>Beta</sup> | Invoice issued       | An invoice, deposit invoice, balance invoice, or credit note is generated |
| `payment.created` <sup>Beta</sup> | New payment recorded | A payment is added to a booking                                           |
| `payment.updated` <sup>Beta</sup> | Payment modified     | Payment information is updated (amount, status, dates...)                 |
| `payment.deleted` <sup>Beta</sup> | Payment removed      | A payment is deleted                                                      |

<Note>
  Invoice and payment events are currently in **beta**: their payload structure may still evolve before general availability.
</Note>

Each resource has a dedicated page with payload examples and field reference:

<CardGroup cols={2}>
  <Card title="Account Events" icon="building" href="/api-reference/webhooks/accounts">
    Companies: created, updated, deleted
  </Card>

  <Card title="Contact Events" icon="user" href="/api-reference/webhooks/contacts">
    People: created, updated, deleted
  </Card>

  <Card title="Invoice Events" icon="file-invoice" href="/api-reference/webhooks/invoices">
    Full invoice payload: amounts, lines, frozen seller/buyer blocks, e-invoicing fields
  </Card>

  <Card title="Payment Events" icon="credit-card" href="/api-reference/webhooks/payments">
    Lightweight payment payload with invoice and booking correlation keys
  </Card>
</CardGroup>

<Note>
  You can subscribe to multiple events in a single webhook. Select only the events you need to reduce unnecessary traffic.
</Note>

## Webhook Payload Structure

All webhooks follow this consistent structure:

```json theme={null}
{
  "event": "contact.created",
  "timestamp": 1731493800000,
  "venue_id": "venue123",
  "venues_group_id": "group456",
  "data": {
    // Event-specific data (see examples below)
  }
}
```

### Payload Fields

| Field             | Type           | Description                                            |
| ----------------- | -------------- | ------------------------------------------------------ |
| `event`           | string         | The event type (e.g., `contact.created`)               |
| `timestamp`       | number         | Unix timestamp in milliseconds when the event occurred |
| `venue_id`        | string         | The venue ID where the change happened                 |
| `venues_group_id` | string \| null | The venues group ID if applicable                      |
| `data`            | object         | Event-specific data containing the resource details    |

## HTTP Headers

Each webhook request includes these headers:

```http theme={null}
Content-Type: application/json
User-Agent: Bookingshake-Webhooks/1.0
Bookingshake-Signature: <hmac-sha256-signature>
Idempotency-Key: <unique-uuid>
```

### Header Details

| Header                   | Description                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `Content-Type`           | Always `application/json`                                                                           |
| `User-Agent`             | Identifies the request as coming from BookingShake webhooks                                         |
| `Bookingshake-Signature` | HMAC SHA256 signature for verifying authenticity (see [Security](/api-reference/webhooks/security)) |
| `Idempotency-Key`        | Unique UUID for this delivery attempt - use to prevent duplicate processing                         |

## Custom Fields

Account and contact webhooks include custom fields configured for your venue (invoice and payment payloads do not expose custom fields). Custom fields are prefixed with `custom_` followed by a UUID:

```json theme={null}
{
  "event": "contact.created",
  "data": {
    "id": "contact-456",
    "first_name": "John",
    "last_name": "Doe",
    "custom_5d07ff93-9b23-4e37-8654-4661fcfd8da8": "VIP Customer",
    "custom_7a12bc34-5de6-4f78-9012-3456789abcde": [0, 1, 2]
  }
}
```

<Note>
  Custom field values can be strings, numbers, arrays, or objects depending on your field configuration.
</Note>

## Venue vs Venues Group Webhooks

When creating a webhook, you can choose the scope:

**Venue-level webhooks**: Receive events only for a specific venue

* Use when you want separate webhook endpoints per venue
* Useful for venue-specific integrations

**Venues group webhooks**: Receive events for all venues in a group

* Use when you want a single endpoint for multiple venues
* More efficient for managing multi-venue organizations
* The `venue_id` field identifies which venue triggered the event

## Next Steps

<CardGroup cols={2}>
  <Card title="Security & Verification" icon="shield-halved" href="/api-reference/webhooks/security">
    Learn how to verify webhook signatures and implement security best practices
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/errors">
    Understand error codes and how to handle failures
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the BookingShake API for additional functionality
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@bookingshake.com">
    Contact our support team for assistance
  </Card>
</CardGroup>

## Rate Limits and Delivery

<Note>
  **Delivery timeout**: Your endpoint must respond within 5 seconds with a `200-299` status code.

  **Retry policy**: Failed deliveries are automatically retried up to 10 times with exponential backoff.

  **Status monitoring**: Check your webhook status in the dashboard to track delivery success and failures.
</Note>