Event Webhook¶

The Talkable Event Webhook notifies your endpoint that an Event or a Purchase has been registered with Talkable.

Use cases for the Event Webhook include:

Capturing purchases and custom referral events generated by the customer (e.g. added data to profile or renewed a subscription)
Tracking coupon codes used for purchases
Using Talkable events to trigger custom workflows (e.g. add a custom property to a customer who just cancelled a subscription)

When does Talkable call the Event Webhook?

Talkable calls the Event Webhook any time an Event or a Purchase is registered either via the front-end Talkable integration or using the Talkable backend API.

Payload parameters provided

origin — subhash of data describing the event that triggered the webhook.
- type
  - “Purchase” for purchases.
  - “Event” for custom events.
For Purchase:
- email — email address associated with the Purchase
- order_number — unique identifier of the Purchase
- customer_id — unique external identifier of a customer who made the purchase
- subtotal — order subtotal for the purchase
- coupon_code — coupon code used with the purchase
- currency_iso_code — currency ISO code of the Purchase
- traffic_source — traffic source of the Purchase
- ip_address — IP address of the Purchase
For Event:
- email — email address associated with the Event
- event_category — identifier of an action that trigger the Event (e.g. app_installed)
- event_number — unique identifier of the Event within the associated event_category
- customer_id — unique external identifier of a customer who triggered the event
- subtotal — optional monetary attribute of the Event
- currency_iso_code — currency ISO code of the Event
- coupon_code — optional coupon code associated with the Event
- traffic_source — traffic source of the Event
- ip_address — IP address of the Event
person — subhash of data describing the person who triggered the event
- email — person’s email address
- phone_number — person’s phone number (optional)
- first_name — person’s first name (optional)
- last_name — person’s last name (optional)
- username — person’s username (optional)
- sub_choice — subscription choice (optional, present only if the form included subscription checkbox)
- subscribed_at — date person has subscribed (deprecated; use opted_in_at instead)
- opted_in_at — date person has subscribed (optional)
- phone_opted_in_at — date person has subscribed with email (optional)
- unsubscribed_at — date person has unsubscribed with phone number (optional)
- custom_properties — hash of person’s custom properties (optional)
- is_loyalty_member — whether the person participates in loyalty program
- loyalty_member — details of the person as a loyalty program participant (optional)
- referral_counts — referral counts of person as Advocate
  - total — created referrals count
  - approved — approved referrals count
  - pending — count of waiting for approval referrals
- gender [deprecated]

Sample payload | Event

{
  "origin": {
    "id": 289738874,
    "type": "Event",
    "email": "referrer@example.com",
    "event_number": "953205549",
    "event_category": "webhook-test",
    "subtotal": 91.52,
    "customer_id": "865955119",
    "order_date": "2019-04-11T07:26:17.272-07:00",
    "coupon_code": "WHT28499",
    "currency_iso_code": "USD",
    "ip_address": "127.0.0.1",
    "traffic_source": "post-event"
  },
  "person": {
    "first_name": "Bob",
    "last_name": "Smith",
    "email": "referrer@example.com",
    "phone_number": null,
    "username": "username",
    "unsubscribed_at": null,
    "subscribed_at": "2019-04-11T07:25:17.272-07:00",
    "opted_in_at": "2019-04-11T07:25:17.272-07:00",
    "phone_opted_in_at": null,
    "sub_choice": true,
    "custom_properties": {},
    "referral_counts": {
      "total": 0,
      "approved": 0,
      "pending": 0
    },
    "is_loyalty_member": false,
    "loyalty_member": null,
    "gender": null
  }
}

cURL example | Event

curl <url> \
     -d "key=<key>" \
     -d "site=<site>" \
     -d "type=event_web_hook" \
     -d "extras={}" \
     -d 'payload={"origin":{"id":289738874,"type":"Event","email":"referrer@example.com","event_number":"953205549","event_category":"webhook-test","subtotal":91.52,"customer_id":"865955119","order_date":"2019-04-11T07:26:17.272-07:00","coupon_code":"WHT28499","currency_iso_code":"USD","ip_address":"127.0.0.1","traffic_source":"post-event"},"person":{"first_name":"Bob","last_name":"Smith","email":"referrer@example.com","phone_number":null,"username":"username","unsubscribed_at":null,"subscribed_at":"2019-04-11T07:25:17.272-07:00","opted_in_at":"2019-04-11T07:25:17.272-07:00","phone_opted_in_at":null,"sub_choice":true,"custom_properties":{},"referral_counts":{"total":0,"approved":0,"pending":0},"is_loyalty_member":false,"loyalty_member":null,"gender":null}}'

Sample payload | Purchase

{
  "origin": {
    "id": 654689661,
    "type": "Purchase",
    "email": "referrer@example.com",
    "order_number": "426692385",
    "subtotal": 29.39,
    "customer_id": "162638070",
    "order_date": "2019-04-11T07:28:31.258-07:00",
    "coupon_code": "WHT79679",
    "currency_iso_code": "USD",
    "ip_address": "127.0.0.1",
    "traffic_source": "post-checkout"
  },
  "person": {
    "first_name": "Bob",
    "last_name": "Smith",
    "email": "referrer@example.com",
    "phone_number": "+12025551111",
    "username": "username",
    "unsubscribed_at": null,
    "subscribed_at": "2019-04-11T07:27:31.258-07:00",
    "opted_in_at": "2019-04-11T07:27:31.258-07:00",
    "phone_opted_in_at": "2019-04-11T07:27:31.258-07:00",
    "sub_choice": true,
    "custom_properties": {},
    "referral_counts": {
      "total": 0,
      "approved": 0,
      "pending": 0
    },
    "is_loyalty_member": false,
    "loyalty_member": null
  }
}

cURL example | Purchase

curl <url> \
     -d "key=<key>" \
     -d "site=<site>" \
     -d "type=event_web_hook" \
     -d "extras={}" \
     -d 'payload={"origin":{"id":654689661,"type":"Purchase","email":"referrer@example.com","order_number":"426692385","subtotal":29.39,"customer_id":"162638070","order_date":"2019-04-11T07:28:31.258-07:00","coupon_code":"WHT79679","currency_iso_code":"USD","ip_address":"127.0.0.1","traffic_source":"post-checkout"},"person":{"first_name":"Bob","last_name":"Smith","email":"referrer@example.com","phone_number":"+12025551111","username":"username","unsubscribed_at":null,"subscribed_at":"2019-04-11T07:27:31.258-07:00","opted_in_at":"2019-04-11T07:27:31.258-07:00","phone_opted_in_at":"2019-04-11T07:27:31.258-07:00","sub_choice":true,"custom_properties":{},"referral_counts":{"total":0,"approved":0,"pending":0},"is_loyalty_member":false,"loyalty_member":null}}'