About Webhook Notifications
An Apptoto Webhook Action is simply a HTTP POST request made from Apptoto’s servers to an URL endpoint of your choosing. A Webhook Action can transmit data from Apptoto across the web to another system or third party product and is a powerful tool that can be used for reporting purposes or integrating services with Apptoto.
Setup
To setup a Webhook Action to respond to triggers, click the Webhook “add” button in the Webhook Triggers section under the trigger form after creating a trigger or clicking a trigger’s settings button:
This will result in a new form rendering below the trigger form that allows you to configure a Webhook Action:
To setup a Webhook Action, select “Send webhook notification” under the “Webhook Action Type” field. Upon selecting this value, a “Webhook URL” field appears; this field stores the web endpoint (e.g. an API endpoint or a Zapier URL) that the Webhook Trigger will attempt to reach when the trigger executes. As with any of the other types of Webhook Triggers, a name field is provided so that you can assign an identifier to the Webhook Action and easily find it later.
Webhook Action Payloads
When a Webhook Action occurs as a result of a trigger being triggered, Apptoto will make a HTTP POST request to the endpoint specified in the Webhook Trigger settings. When this happens, the HTTP request is accompanied with information stored in a JSON format about the object that the trigger is based on, as well as an identifier that corresponds to the instance of the Webhook Action running. The exact structure of this payload depends on the type of trigger that the Webhook Action corresponds to (e.g. a Webhook Action for an event-based trigger will contain information regarding an event, where a Webhook Action setup for a message-based trigger will send information relating to a message.) The exact structure of the payload for individual triggers are as follows:
Event-Based Triggers (“New event is created”, “Event is updated”, “Event is deleted”):
| JSON Attribute | Description |
|---|---|
| event | Event object (object) |
| id | Event ID (integer) |
| calendar_id | Calendar ID (integer) |
| calendar_name | Calendar name (string) |
| external_id | External Event ID (string) |
| start_time | Event start time (date) |
| end_time | Event end time (date) |
| all_day | All day (boolean) |
| title | Event title (string) |
| location | Event location (string) |
| content | Event content (string) |
| participants | (array of objects) |
| id | Participant ID (integer) |
| event_id | Event ID (integer) |
| display_name | Participant display name (string) |
| name | Participant name (string) |
| phone | Participant phone (string) |
| normalized_phone | Participant normalized phone number (string) |
| Email for participant (string) | |
| state | Reminder state or booking state (string) |
| custom_data | Custom data properties for event (object) |
| is_deleted | Indicates if event has been deleted (boolean) |
| apptoto_id | Unique identifier for webhook (string) |
Participant-Based Triggers (“Participant reminder state changed”, “Participant confirmed”, “Participant not coming”, et al.)
| JSON Attribute | Description |
|---|---|
| participant | Participant object (object) |
| id | Participant ID (integer) |
| event_id | Event ID (integer) |
| display_name | Participant display name (string) |
| name | Participant name (string) |
| phone | Participant phone (string) |
| normalized_phone | Participant normalized phone (string) |
| email (string) | |
| event | Event object (object) |
| id | Event ID (integer) |
| calendar_id | Calendar ID (integer) |
| calendar_name | Calendar name (string) |
| external_id | Event external ID (string) |
| start_time | Event start time (date) |
| end_time | Event end time (date) |
| all_day | Event is all day (boolean) |
| title | Event title (string) |
| location | Event location (string) |
| content | Event content (string) |
| custom_data | Custom field information (array of objects) |
| is_deleted | Event has been deleted (boolean) |
| apptoto_id | Unique identifier for webhook (string) |
Booking Page-Based Triggers (“Booking Page is viewed”)
| JSON Attribute | Description |
|---|---|
| booking_page | Booking page object (object) |
| id | Booking page ID (integer) |
| name | Booking page name (string) |
| url | Booking page URL (string) |
| apptoto_id | Unique identifier for webhook (string) |
Booking Request-Based Triggers (“Booking request is completed”)
| JSON Attribute | Description |
|---|---|
| booking_request | Booking request object (object) |
| token | Booking request token (string) |
| state | Booking request state (string) |
| appointment_type_token | Appointment type token (string) |
| occurrence_selected_event_id | Event ID of occurrence selected (integer) |
| start_time | Booking start time (date) |
| end_time | Booking end time (date) |
| sign_up_page | Booking page is sign up page (boolean) |
| timezone | Contact timezone (string) |
| field_data | Custom field data (object) |
| contact_info | Contact info object (object) |
| name | Contact name (string) |
| phone | Contact phone (string) |
| Contact email (string) | |
| booking_page | (object) |
| id | Booking page ID (integer) |
| name | Booking page name (string) |
| url | Booking page URL (string) |
| apptoto_id | Unique identifier for webhook (string) |
Message-Based Triggers (“Message sent”, “Message received”)
| JSON Attribute | Description |
|---|---|
| message | Message object (object) |
| id | Message ID (integer) |
| participant | Participant object (object) |
| id | Participant ID (integer) |
| event_id | Event ID (integer) |
| display_name | Participant display name (string) |
| name | Participant name (string) |
| phone | Participant phone (string) |
| normalized_phone | Participant normalized phone (string) |
| Participant email (string) | |
| state | Participant reminder/ booking state (string) |
| started | Message started sending at (date) |
| comm_type | Communication type (string) |
| last_out | Last message out (date) |
| last_in | Last message in (date) |
| apptoto_id | Unique identifier for webhook (string) |
Phone number is added to stoplist
| JSON Attribute | Description |
|---|---|
| phone | phone number (string) |
| apptoto_id | Unique identifier for webhook (string) |
Email is added to stoplist
| JSON Attribute | Description |
|---|---|
| email (string) | |
| apptoto_id | Unique identifier for webhook (string) |
Logging
For each Webhook Action setup, you can view instances of the Webhook Action by clicking the “Log” button:
For a Webhook Action, this will return a table listing the instances in reverse chronological order, with their corresponding state or status, indications of whether the Webhook Action was successfully sent from Apptoto and delivered (received by target system), number of attempts, as well as means of inspecting the payload and response for each instance. You can also filter logs based on whether or not the Webhook Action is successful, as well as sort the table by individual columns.
Webhook Action Attempts
Webhook Actions in Apptoto are different from other types of Webhook Triggers in the sense that failed Webhook Actions will retry in certain circumstances.
In Apptoto, a Webhook Action is considered successful when a HTTP 200 response is returned from the server that Apptoto is doing a POST request against.
If the resource that Apptoto is posting against encounters a 500 series error (e.g. a 500 internal server error or a 502 bad gateway error), Apptoto assumes that the problem might be temporary and will retry the request again up to five attempts.
If a 400 series error is returned when the Webhook Action request is made (e.g. a 403 forbidden error or a 404 not found error), Apptoto will assume that a configuration error was made when setting up the webhook or that the webhook endpoint isn’t valid and thus the request instance should not be reattempted.