> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.cal.id/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Webhook in Cal ID

Webhooks are a great way to automate flows with other apps when invitees schedule, cancel, or reschedule events. A webhook subscription lets you listen for specific trigger events — like a booking being created — by pointing Cal ID at a subscriber URL. You can build your own listener, or trigger automations without code using the Zapier integration. Webhooks can be attached to your account or to individual event types, including team event types.

| Create a webhook subscription

Visit `/settings/webhooks` and enter:

1. **Subscriber URL:** the listener URL that receives the payload when a trigger fires.
2. **Event triggers:** choose which triggers to listen to. Available triggers:
* `Booking Created`
* `Booking Requested`
* `Booking Rescheduled`
* `Booking Cancelled`
* `Booking Rejected`
* `Booking Payment Initiated`
* `Booking Paid`
* `Booking No-show Updated`
* `Form Submitted`
* `Out-of-office Created`
3. **Secret:** provide a secret key to verify payloads on your subscriber URL (confirms a payload is authentic and untampered). Leave blank to skip.
4. **Custom Payload:** optionally customize the payload you receive.

![](https://storage.crisp.chat/users/helpdesk/website/-/6/f/1/c/6f1c2c7b8034d000/image_sm2h6y.png =1222x615)

| An example webhook payload

```
{
    "triggerEvent": "BOOKING_CREATED",
    "createdAt": "2023-05-24T09:30:00.538Z",
    "payload": {
        "type": "60min",
        "title": "60min between Pro Example and John Doe",
        "description": "",
        "additionalNotes": "",
        "customInputs": {},
        "startTime": "2023-05-25T09:30:00Z",
        "endTime": "2023-05-25T10:30:00Z",
        "organizer": {
            "id": 5,
            "name": "Pro Example",
            "email": "pro@example.com",
            "username": "pro",
            "timeZone": "Asia/Kolkata",
            "language": { "locale": "en" },
            "timeFormat": "h:mma"
        },
        "attendees": [
            {
                "email": "john.doe@example.com",
                "name": "John Doe",
                "timeZone": "Asia/Kolkata",
                "language": { "locale": "en" }
            }
        ],
        "location": "Cal ID HQ",
        "eventTypeId": 7,
        "uid": "bFJeNb2uX8ANpT3JL5EfXw",
        "eventTitle": "60min",
        "length": 60,
        "bookingId": 91,
        "status": "ACCEPTED"
    }
}
```

| Verify the authenticity of a payload

1. Add a **secret key** to your webhook and save.
2. Wait for the webhook to fire (a booking is created, cancelled, rescheduled, and so on).
3. Use the secret key to create an `hmac`, then combine it with the received payload to produce a SHA256 signature.
4. Compare your hash with the one in the webhook's `X-Cal-Signature-256` header. If they don't match, the payload was altered and can't be trusted.

| Adding a custom payload template

Custom payloads reduce development effort and often remove the need to build a separate integration service. Example template:

```
{
  "content": "A new event has been scheduled",
  "type": "{{type}}",
  "name": "{{title}}",
  "organizer": "{{organizer.name}}",
  "booker": "{{attendees.0.name}}"
}
```

Here `{{type}}` is the event type slug and `{{title}}` is the event type name. Wrap variables in double curly braces as shown. The supported variables:

| Variable | Type | Description |
| ---- |
| triggerEvent | String | The trigger event: BOOKING\_CREATED, BOOKING\_REQUESTED, BOOKING\_RESCHEDULED, BOOKING\_CANCELLED, BOOKING\_REJECTED, BOOKING\_PAYMENT\_INITIATED, BOOKING\_PAID, BOOKING\_NO\_SHOW\_UPDATED, FORM\_SUBMITTED, OOO\_CREATED |
| createdAt | Datetime | The time of the webhook |
| type | String | The event type slug |
| title | String | The event type name |
| startTime | Datetime | The event's start time |
| endTime | Datetime | The event's end time |
| description | String | The event's description from the event type settings |
| location | String | Location of the event |
| organizer | Person | The organizer of the event |
| attendees | Person | The event booker and any guests |
| uid | String | The UID of the booking |
| rescheduleUid | String | The UID of the rescheduling |
| cancellationReason | String | Reason for cancellation |
| rejectionReason | String | Reason for rejection |
| team.name | String | Name of the team booked |
| team.members | String | Members of the team booked |
| metadata | JSON | Booking metadata, including the meeting URL (videoCallUrl) for Google Meet |

### Person structure

| Variable | Type | Description |
| ---- |
| name | String | Name of the individual |
| email | Email | Email of the individual |
| timezone | String | Timezone of the individual (e.g., "America/New\_York", "Asia/Kolkata") |
| language?.locale | String | Locale of the individual (e.g., "en", "fr") |

### Razorpay Payment Details in Webhook Payloads

For users integrating Cal ID with invoicing or other external systems, Razorpay payment details are now available directly in the webhook payload.
These parameters are included under:
`body → metadata`

#### Available Parameters
| Parameter | Description |
| ---- |
| `paymentExternalId` | Payment link ID or payment intent ID, depending on how the payment was initiated by the payment provider. |
| `transactionId` | The actual Razorpay payment ID. |
| `accountId` | The Cal ID payment account ID associated with the transaction. |
| `paymentLink` | The Razorpay payment link associated with the transaction. |

#### Example Webhook Payload
```
{
  "metadata": {
    "paymentExternalId": "<payment_link_id_or_intent_id>",
    "transactionId": "<actual_payment_id>",
    "accountId": "<account_id>",
    "paymentLink": "<payment_link>"
  }
}
```

#### How to Use These Fields
If you are using Cal ID webhooks with tools such as **Pabbly Connect, Zapier, Make, Zoho Invoice**, or other external systems, you can now use these fields to automate payment and invoicing workflows.
For example:
1. A customer opens the Cal ID booking link.
2. The customer makes a booking and initiates a Razorpay payment.
3. Cal ID sends the relevant webhook event.
4. The webhook payload includes the payment information under `body → metadata`.
5. Use `transactionId` to capture the actual Razorpay Payment ID.
6. Use `paymentLink` if you need the Razorpay payment link for reference or reconciliation.
7. Pass these values to your invoicing or accounting system.

**Important:** `paymentExternalId` and `transactionId` serve different purposes. `paymentExternalId` contains the external payment link/intent identifier, while `transactionId` contains the actual payment transaction ID generated by Razorpay.