Webhooks

Webhooks are “user-defined HTTP callbacks” triggered by events on Talkable’s site. Subscribing to Talkable Webhooks allows you to receive notifications about various events from Talkable, for example, when a Reward should be given, or when a Friend or Advocate opts in to an email newsletter subscription.

After subscribing to a Webhook, your app can execute code immediately after specific events occur in Talkable.

https://en.wikipedia.org/wiki/Webhook

Each Webhook in Talkable is defined with an HTTP URL to deliver Webhook data (aka payload). This URL should be defined and implemented on the client’s site.

Available Webhooks

Below is a user experience flow showing when Talkable Webhooks are called. For more details concerning specific Talkable Webhooks, click the appropriate Webhook type in the left-hand menu.

Webhooks Flowchart

Note

The Reward Webhooks will only send if there is an associated incentive configured. For example, for the ‘Reward Webhook’ (reason = signup) to send, there must be a signup incentive configured in the campaign rules.

Set Up

Webhooks Menu Item

  1. Set up and test Talkable Webhooks by navigating to Menu then Webhooks

  2. Proceed to Create New Webhook

  3. Choose a Webhook from the dropdown and provide your endpoint URL

  4. From here, Send Sample, Edit, Delete or Create New

  5. Take note of your Talkable security key. This key will be the same for all Talkable Webhooks on a given site. Talkable includes a key parameter in Webhooks which are unique to each site as a way to identify Talkable as an authorized server. Your Talkable Webhook security key can be found in the Webhook set up page.

Talkable Webhooks will trigger automatically based on associated events defined by Webhook type.

Testing

Testing webhooks can be accomplished with the help of Webhook Tester, an external service that tests your post-receive messages.

  1. Visit Webhook Tester and click Copy to copy the URL you are given.

  2. Open your site on Webhooks set up page.

  3. Click New.

  4. Select webhook type.

  5. Paste your Webhook Tester URL and save.

  6. Click Deliver Sample near the webhook you want to test.

  7. After you finish the implementation on your site change Webhook Tester URL to the live URL on your site.

  8. Click Deliver Sample to test webhook with Live URL.

Data

All Webhooks are delivered as an HTTP Post request with the main parameter called payload. All data inside this parameter is encoded as JSON. Below is a PHP parameter decode example:

json_decode($_POST["payload"])

Parsing Timestamps

Timestamp data type is not a part of JSON standard. Timestamps are passed as strings in ISO 8601 compatible format. To function properly, ensure your date parser is compatible to this standard. Java users go here:
https://stackoverflow.com/questions/2201925/converting-iso-8601-compliant-string-to-java-util-date

Response Codes

Talkable considers a Webhook as “delivered successfully” when a site server returns a 2xx response status. Otherwise Talkable will continually retry to deliver a Webhook after a set interval of time.

HTTP Responses and Their Meanings

  • 2xx: Success

  • 200: OK

  • 201: Created

  • 202: Accepted

  • 203: Non Authoritative Information

  • 204: No Content

  • 205: Reset Content

  • 206: Partial Content

If you have a problem on your server, you can answer with code 500. If there is some problem in our request (problem on Talkable’s side), you can answer “400 Bad Request”.

Talkable will retry delivery of Webhook if any other error code is received.

Security Key

Talkable includes a key parameter in Webhooks which are unique to each site as a way to identify Talkable as an authorized server. Your Talkable Webhook security key can be found in the Webhook set up page.

Type

The type parameter of a Webhook request can be used to identify which Webhook is received without looking at the payload. This will be useful if you point multiple Webhooks to the same URL; for instance, for data collection purposes.

Possible types are:

  • referral_web_hook

  • create_coupon_web_hook

  • post_share_web_hook

  • offer_signup_web_hook

  • claim_signup_web_hook

  • reward_web_hook

  • unsubscribe_web_hook

  • check_unsubscribe_web_hook

  • event_web_hook

Site

Every Webhook has a site parameter that identifies which Talkable site sent this request. This is useful if you have a multi-site setup or use a staging site.

Whitelisting Talkable IPs

In case your servers are behind firewall, you may need to whitelist Talkable IP addresses so webhooks can be delivered. Pass list of these addresses to your network administrator:

  • 100.26.94.244

  • 18.207.91.200

  • 18.210.165.17

  • 18.232.203.127

  • 18.233.48.151

  • 184.73.206.68

  • 23.21.155.129

  • 3.222.226.72

  • 34.197.54.191

  • 34.226.253.236

  • 34.231.104.179

  • 34.232.247.192

  • 35.169.186.170

  • 35.171.77.58

  • 35.173.87.187

  • 44.217.136.252

  • 44.219.211.174

  • 50.16.143.102

  • 50.17.244.178

  • 52.204.148.18

  • 52.22.0.55

  • 52.6.41.1

  • 52.7.94.243

  • 54.164.128.44

  • 54.208.14.192

  • 54.86.208.153

  • 54.86.241.218

  • 54.91.51.228

Compatibility and Versioning

Talkable Webhooks do not currently incorporate versioning. Current spec will not be changed for all existing hooks. Note that Talkable may add additional data elements to existing Webhooks, but should not remove or change existing data elements.

See available Webhooks on the navigation sidebar.