Create a webhook
Login to the Butlerapp
In the left menu, under the Settings section, select Webhook Configurations
On the top right corner, click on plus button to add a new webhook
Enter a Name for the webhook to make it easier to identify.
Choose the entities you want the webhook to notify you about. You can select one or more entities in the selection, webhook will be fired for the selected entities.
Enter the Endpoint URL. Webhooks will be sent to this address. The endpoint URL should be prefixed with either https:// or http://.
Enter an X-Webhook-Signature header key. This key will be included in the header of your webhook to validate that the notification was sent from Butlerapp.
On the top right corner, click on save button to create the webhook.
You can register up to 15 webhook endpoints, selecting the entities you'd like to receive notifications for.
Once you've created the webhook, we'll start sending relevant notifications to the specified endpoint.
Note that your webhook endpoint must respond with status code 200. If the status code is not 200, then Butlerapp will retry a failed webhook for up to 3 times with 30 seconds delay in each try.
Sample Payload
{
"data": [
{
"type": "prices",
"id": 545,
"action": "deleted",
"attributes": [],
}
]
}
Explanation of payload
type this is the entity for which webhook is fired. Possible values are
bills
bill_positions
course_participants
bank_transactions
statistics
consents
personal_data
exams
outgoing_messages
course_timespans
courses
course_appointments
prices
tags
id is the record on which action was performed
action this is action performed on the entity. Possible values are
created
updated
deleted
attributes object of the values which were effected in this action, for create and update this will not be empty, but for delete action, it will be empty
If there are multiple entities affected in one request, all will be sent in one payload, for example when a booking is created, along the booking a participant might also be created or updated, so Butlerapp will send booking and participant in same webhook. for example, in below sample payload, We had selected "Booking" and "Personal" from the Type of webhook dropdown, so when we created a booking, it created booking and also it created a new participant
{
"data": [
{
"type": "personal_data",
"id": 1553,
"action": "created",
"attributes": {
"user_id": 1793,
"creator_id": 1,
"salutation_id": "3",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@yopmail.com",
"title": "",
"company": "",
"mobile_phone": "0300",
"phone": "0300",
"street": "Unter den Linden 30",
"postal_code": "44000",
"place": "Berlin",
"country_id": "57",
"is_phone_sanitized": false,
"updated_at": "2025-02-11 14:45:31",
"created_at": "2025-02-11 14:45:31",
"id": 1553
}
},
{
"type": "course_participants",
"id": 2859,
"action": "created",
"attributes": {
"creator_id": 1,
"group_identifier": "7OR0MwbT9ZFnYMFLbGr7ipMyjY49Rw",
"personal_data_id": 1553,
"course_timespan_id": 1237,
"price_id": null,
"comment": null,
"quantity": "1",
"unique_id": "BBMH-LBLA",
"updated_at": "2025-02-11 14:45:31",
"created_at": "2025-02-11 14:45:31",
"id": 2859,
"finalized_at": {
"date": "2025-02-11 14:45:31",
"timezone_type": 3,
"timezone": "Europe/Berlin"
}
}
}
]
}
Below is the sample webhook payload of a booking created for scheduling offer, kindly note that for each scheduling offer booking there is an offer (course_timespan) created as well.
{
"data": [
{
"type": "personal_data",
"id": 2095,
"action": "created",
"attributes": {
"user_id": 1662,
"creator_id": 1662,
"email": "natallia@butlerapp.de",
"salutation_id": "2",
"first_name": "Natallia",
"last_name": "Test",
"title": "",
"company": "",
"is_phone_sanitized": false,
"updated_at": "2025-06-04 14:20:59",
"created_at": "2025-06-04 14:20:59",
"id": 2095
}
},
{
"type": "course_timespans",
"id": 1111,
"action": "created",
"attributes": {
"creator_id": 1,
"site_type_id": 5,
"title": "",
"body": "",
"is_agreement": 0,
"place_id": 1,
"max_bookings": 30,
"active_until": {
"date": "2025-06-17 11:45:00",
"timezone_type": 3,
"timezone": "Europe\/Berlin"
},
"document_template_id": null,
"message_template_id": null,
"prepayment_percentage": 100,
"is_bookable_without_price": 0,
"shortcut_template": "Event A",
"body_2": "",
"collect_participant_address": 0,
"collect_participant_email": 1,
"collect_participant_phone": 0,
"collect_participant_mobile": 0,
"collect_participant_birthday": 0,
"collect_participant_title": 0,
"collect_participant_birthplace": 0,
"hide_has_bill_personal_data": 0,
"has_bill_personal_data": 0,
"top_form_item_id": 71698,
"participant_form_item_id": 71703,
"bill_receiver_form_item_id": 71710,
"max_quantity_courses": 10,
"collect_participant_company": 0,
"schedule_max_days_in_future": 90,
"course_timespan_type_id": 3,
"scheduling_parent_id": 1109,
"dont_collect_participant_information": 0,
"course_timespan_participation_type_id": 1,
"min_quantity_courses": 1,
"cancel_message_template_id": null,
"consent_form_item_id": 71715,
"archived_at": null,
"active_until_days": 0,
"beschreibung3": "",
"beschreibung4": "",
"beschreibung5": "",
"is_participant_age_validated": 0,
"min_age": null,
"max_age": null,
"waitlist_type_id": null,
"waitlist_max_limit": null,
"booking_cancellation_type_id": 2,
"cancellable_before_days": null,
"video_comm_service_id": null,
"max_teachers": null,
"to": "2025-06-17 12:00:00",
"updated_at": "2025-06-04 14:20:59",
"created_at": "2025-06-04 14:20:59",
"id": 1111,
"from": "2025-06-17 11:45:00",
"categories": [
"Event A"
],
"other_description_1": "",
"other_description_2": "",
"other_description_3": "",
"other_description_4": ""
}
},
{
"type": "course_participants",
"id": 3400,
"action": "created",
"attributes": {
"creator_id": 1662,
"group_identifier": "fxY05If8wqQNIEsDsV2GhQ66b6zHIw",
"personal_data_id": 2095,
"course_timespan_id": 1111,
"price_id": 287,
"comment": null,
"quantity": "1",
"unique_id": "BCSH-VOKM",
"updated_at": "2025-06-04 14:20:59",
"created_at": "2025-06-04 14:20:59",
"id": 3400,
"finalized_at": {
"date": "2025-06-04 14:20:59",
"timezone_type": 3,
"timezone": "Europe\/Berlin"
},
"price": "100.00",
"tax": "15.97",
"net_price": "84.03",
"balance": "-100.00",
"due_amount": "100.00",
"due_date": "2025-06-14 11:45:00"
}
},
{
"type": "bill_positions",
"id": 265,
"action": "created",
"attributes": {
"creator_id": 1662,
"bill_id": 192,
"price_id": 287,
"position_type_id": 5,
"quantity": "1",
"course_timespan_id": 1111,
"parent_position_id": null,
"article_id": null,
"order_id": null,
"base_title": "Event A 17.06.2025 ",
"base_single_price": 100,
"tax_rate": "19.00",
"single_price": 100,
"title": "Event A 17.06.2025 ",
"price": 100,
"tax": 15.97,
"net_price": 84.03,
"updated_at": "2025-06-04 14:20:59",
"created_at": "2025-06-04 14:20:59",
"id": 265
}
}
]
}
Below is the sample webhook payload of a booking created for scheduling offer. This offer was booked with the cart, so it created multiple bookings for each participant, and all of the bookings' payload is part of the one webhook.
{
"data": [
{
"type": "personal_data",
"id": 570,
"action": "updated",
"attributes": {
"updated_at": "2025-06-04 14:24:07",
"company": "",
"email": "natallia1@butlerapp.de",
"is_mobile_phone_sanitized": false,
"is_phone_sanitized": false
}
},
{
"type": "personal_data",
"id": 2098,
"action": "created",
"attributes": {
"user_id": 1360,
"creator_id": 1360,
"email": "natallia2@butlerapp.de",
"salutation_id": "2",
"first_name": "Natallia",
"last_name": "Test2",
"is_phone_sanitized": false,
"updated_at": "2025-06-04 14:24:07",
"created_at": "2025-06-04 14:24:07",
"id": 2098
}
},
{
"type": "personal_data",
"id": 2099,
"action": "created",
"attributes": {
"user_id": 1360,
"creator_id": 1360,
"email": "natallia3@butlerapp.de",
"salutation_id": "2",
"first_name": "Natallia",
"last_name": "Test3",
"is_phone_sanitized": false,
"updated_at": "2025-06-04 14:24:07",
"created_at": "2025-06-04 14:24:07",
"id": 2099
}
},
{
"type": "course_participants",
"id": 3404,
"action": "created",
"attributes": {
"creator_id": 1360,
"group_identifier": "2wGsZF4bTKZ2HlGrNa02RKw7ev6IJZ",
"personal_data_id": 570,
"course_timespan_id": 1112,
"price_id": 288,
"comment": null,
"quantity": "1",
"unique_id": "BXLL-WRMX",
"updated_at": "2025-06-04 14:24:07",
"created_at": "2025-06-04 14:24:07",
"id": 3404,
"finalized_at": {
"date": "2025-06-04 14:24:07",
"timezone_type": 3,
"timezone": "Europe\/Berlin"
},
"price": "750.00",
"tax": "119.75",
"net_price": "630.25",
"balance": "-750.00",
"due_amount": "750.00",
"due_date": "2025-06-18 14:24:07"
}
},
{
"type": "course_participants",
"id": 3405,
"action": "created",
"attributes": {
"creator_id": 1360,
"group_identifier": "2wGsZF4bTKZ2HlGrNa02RKw7ev6IJZ",
"personal_data_id": 2098,
"course_timespan_id": 1112,
"price_id": 288,
"comment": null,
"quantity": "1",
"unique_id": "BXWR-VLBK",
"updated_at": "2025-06-04 14:24:07",
"created_at": "2025-06-04 14:24:07",
"id": 3405,
"finalized_at": {
"date": "2025-06-04 14:24:07",
"timezone_type": 3,
"timezone": "Europe\/Berlin"
},
"price": "750.00",
"tax": "119.75",
"net_price": "630.25",
"balance": "-750.00",
"due_amount": "750.00",
"due_date": "2025-06-18 14:24:07"
}
},
{
"type": "course_participants",
"id": 3406,
"action": "created",
"attributes": {
"creator_id": 1360,
"group_identifier": "2wGsZF4bTKZ2HlGrNa02RKw7ev6IJZ",
"personal_data_id": 2099,
"course_timespan_id": 1112,
"price_id": 288,
"comment": null,
"quantity": "1",
"unique_id": "AGFJ-WHVW",
"updated_at": "2025-06-04 14:24:07",
"created_at": "2025-06-04 14:24:07",
"id": 3406,
"finalized_at": {
"date": "2025-06-04 14:24:07",
"timezone_type": 3,
"timezone": "Europe\/Berlin"
},
"price": "750.00",
"tax": "119.75",
"net_price": "630.25",
"balance": "-750.00",
"due_amount": "750.00",
"due_date": "2025-06-18 14:24:07"
}
},
{
"type": "bill_positions",
"id": 267,
"action": "created",
"attributes": {
"creator_id": 1360,
"bill_id": 194,
"price_id": 288,
"position_type_id": 5,
"quantity": 3,
"course_timespan_id": 1112,
"parent_position_id": null,
"article_id": null,
"order_id": null,
"base_title": "Event A 23.07.2025 - 29.07.2025 Fr\u00fchst\u00fcck inkl.",
"base_single_price": 250,
"tax_rate": "19.00",
"single_price": 250,
"title": "Event A 23.07.2025 - 29.07.2025 Fr\u00fchst\u00fcck inkl.",
"price": 750,
"tax": 119.75,
"net_price": 630.25,
"updated_at": "2025-06-04 14:24:07",
"created_at": "2025-06-04 14:24:07",
"id": 267
}
}
]
}