Webhooks

Webhooks allow you to set up integrations that subscribe to certain events in TalkBox. When one of these events occurs TalkBox will send an HTTP POST payload to the webhook’s URL.

Webhook payloads can be consumed by any online system that’s configured to receive them. Webhooks can therefore be used to trigger any function that an external system is capable of and it not limited by TalkBox itself.

In TalkBox the only events that trigger webhooks are contact change events. This allows external systems that store a contact database and keep it synced in real time with TalkBox. Such a system will be notified every time a contact is changed.

Navigation

Tools > Developers > Webhooks

To configure a webhook in the TalkBox interface navigate to Tools > Developers > Webhooks.

From here you can specify the URL and restrict the webhook to contacts that have been changed using certain methods.

Change methods

Selecting just specific change methods can prevent high volumes of change data being generated. 

Method	Description
API	Contact changed made using the API
User	Contact changes made by users logged in to the TalkBox app
Form	Changes made using a TalkBox form
Upload	Contacts changed or added using a file upload in the TalkBox app
Admin	Reserved for changes made by Impact Data staff
Web Page	Changes made on the public unsubscribe page

The URL must use HTTPS as sensitive information will be included in the webhook payload.

Payload

The webhook payload will be a json string of the form shown below. Note that the full contact is returned on change, not just the changed attributes.

    {
      "id": 300,
      "age": 23,
      "anniversary": null,
      "date_of_birth": "2000-01-01T00:00:00+11:00",
      "email": "barry.hall@gmail.com",
      "favourite_marx_bro": [9,10],
      "first_name": "Barry",
      "gender": null,
      "last_name": "Hall",
      "mobile_number": null,
      "created_at": "2023-07-06 02:06:19",
      "unreachable_email": false,
      "unreachable_mobile": false,
      "unsubscribed_email": false,
      "unsubscribed_mobile": false,
      "tags": ["VIP","Gaming"]
    }

The contact information is the value of the parameter ‘data’ and follows the structure of contact data returned by the API.

The “tags” parameter outside of the contact data is used to track integration batches and should not be confused with the contact attribute of the same name.