Basics and Set up

Automatically react to events in TidyHQ using webhooks.

Webhooks in TidyHQ allow your external systems to receive a notification when certain events occur, so you can react proactively.

These work on a organisation-by-organisation basis, and you can configure your endpoint to receive a specific event, multiple events or event wildcard against several types of events.

In turn, when these events occur we'll generate and dispatch an event with a specified payload to your registered URL. We also sign these requests (See Signature Verification for more) to allow you to be confident they're delivered by TidyHQ.

Setting up webhooks

Currently, webhooks are managed via the TidyHQ developer portal or via the appropriate API v2 endpoint.

From here, you must choose:

1. The organisation you have administrator access to, that the webhook will be associated with.
2. A target URL for your to receive events to.
3. An events filter.
4. If the webhook allows state changes (described below)

Once created, you'll receive the signing key used for signature verification, and depending on your choice in step 4, may be initially disabled.

Event Filters

Event filters are a comma-seperated list of patterns, applied against events as they're triggered. You can use wildcards to match multiple events, and the following examples are all valid:

• * - match all events.
• contact.activated,contact.deactivated - only match the contact (de)activate events.
• contact.*,membership.created - all contact events and the membership creation event.

You can see in the Events reference what each event we currently support are - Occasionally, new events will be added before they are documented here which may be caught by the wildcard patterns, so we advise implementing an event router on your side to handle based on the event type.

Allowing state changes & Retry / Failure Handling

The "Allow state changes" checkbox allows you to place your webhook into one of two modes.

The default mode (enabled), means that a webhook starts off by default as disabled. You can click "Activate Webhook" to enable data sending, and you can come back to this page in the future to manually deactivate the webhook if you desire.

Webhooks will try to send to your system up to ten times, spaced at increasing intervals. If the system does not receive a successful response code (2XX) to any of these tries, your webhook will be automatically disabled, and can also be re-enabled in this UI.

If "Allow state changes" is disabled, the webhook starts off in the active state, and you may not manually disable or reenable it. If it enters an error state after failing to send as above, the hook is completely deleted. This mode can be useful if you have a system that automatically provisions webhooks and will reprovision a completely new webhook on error.

Retry Intervals

The retry intervals for when a webhook fails to send are as follows:

Attempt	Interval
1	Instant
2	30 seconds
3	1 minute
4	5 minutes
5	20 minutes
6	1 hour
7	3 hours
8	9 hours
9	1 day
10	3 days

Webhook Payloads

Webhooks use a generalised event container for each item, and then reuse API v2 response types where applicable, e.g. anything involving a contact will return the same type and shape of data as the Contacts endpoint.

The response looks something like:

JSON

{
   "api_version": "2022-12-06",
   "id": "01GTG4P8RTP1QNS9FZ7W7HH87B",
   "webhook_id": "fe45c59dce12",
   "http_method": "POST",
   "kind": "contact.group.added",
   "object": "contact.group",
   "created": 1677726524,
   "data": {
       "created_at": "2023-03-02T03:08:44Z",
       "updated_at": "2023-03-02T03:08:44Z",
       "subscribed": true,
       "member": {
           "id": "2fc5e5c9390c",
           "nick_name": "",
           "first_name": "Joe",
           "last_name": "Bloggs",
           "initials": "JB",
           "created_at": "2022-02-10T05:28:19Z",
           "updated_at": "2023-03-02T03:09:35Z",
           "club_id": "c202c59dce12",
           "full_name": "Joe Bloggs",
           "image": "https://assets.tidyhq.com/image.jpg"
       },
       "group": {
           "id": "f5ed9de37c7f",
           "label": "My Club",
           "description": "",
           "created_at": "2016-03-10T22:34:49Z",
           "updated_at": "2023-03-02T03:08:44Z",
           "size": 2,
           "image": "https://assets.tidyhq.com/image.jpg"
       }
   }
}

In this response, we include:

• The api_version used to generate the webhook.
• The id of the event - these are ULIDs, so are both unique and timesortable lexicographically.
• The webhook_id corresponding to the webhook responsible for sending the event
• The http_method describing which HTTP method the message has been sent via
• The kind of event, matching handlers.
• object - the type of object, list below.
• created - the unix timestamp of event creation.
• Finally, data, the serialized data of the event object at time of creation.

If the event is an "updated" event, there will also be a "changes" key in the data response that describes the keys for which the data has changed, with the prior and current value being listed.

The triggered events API v2 endpoint allows you to see the format of historical events, with the api_version, webhook_id and http_method parameters missing.