Custom App¶
Custom App allows you to send Talkable data to a desired destination such as your site, ESP, CDP. Talkable will send a request with data to the Custom App URL for each customer’s event specified in the Custom App settings.
Set Up¶
Navigate to the App store:
Choose a Custom app and click “Install”
Fill in Endpoint URL and App name fields, and enable the required actions.
Complete installation and enable the app:
Webhook Signature Verification¶
The x-talkable-signature header is included in each request and contains a signature that you have to verify to make sure the request is not compromised.
Talkable generates the signature using a Base64 encoded hash-based message authentication code (HMAC) with SHA-256.
To verify the signature, you should complete the following steps:
1. Prepare the payload_json string
Create a JSON string from the payload of the request.
2. Determine the expected signature
Compute an hex encoded HMAC with the SHA256 hash function. Use the Webhook security key as a key, and use the payload_json string as a message.
Encode a computed hash with Base64
Your Talkable Webhook security key can be found in the Webhook set up page by navigating to Menu then Webhooks.
3. Compare the signatures
Compare the signature from the header with your calculated signature.
Examples:
Ruby:
require 'base64'
require 'openssl'
require 'active_support/security_utils'
WEBHOOK_SECRET_KEY = 'my_webhook_secret'
def verify_webhook(data, header_signature)
calculated_signature = Base64.strict_encode64(OpenSSL::HMAC.hexdigest('sha256', WEBHOOK_SECRET_KEY, data))
ActiveSupport::SecurityUtils.secure_compare(calculated_signature, header_signature)
end
JavaScript:
const crypto = require('crypto');
const WEBHOOK_SECRET_KEY = 'my_webhook_secret';
function verifyWebhook(data, headerSignature) {
// Calculate HMAC
const calculatedSignature = btoa(crypto
.createHmac('sha256', WEBHOOK_SECRET_KEY)
.update(data)
.digest('hex')
);
return crypto.timingSafeEqual(
Buffer.from(calculatedSignature, 'base64'),
Buffer.from(headerSignature, 'base64')
);
}
Available actions¶
Each action allows custom attributes to be included. You can see allowed interpolation variables by clicking Show available variables button:
Referral Create¶
Triggers when a new referral is created, sending detailed information about the referral.
Default payload:
{
"site_id": "1",
"campaign_id": "142",
"referral_status": "in_progress",
"advocate_email": "advocate@example.com",
"friend_email": "friend@example.com"
}
Sync signups¶
This action automatically synchronizes all people whenever they sign up no matter if person opted in by email or phone number.
Default payload:
{
"email": "person-9eb230f8d189fca9@talkable-sample.com",
"email_optin": "true",
"phone_number": "+12025551111",
"phone_optin": "true"
}
Sync email opt-ins¶
This action automatically synchronizes all people whenever they sign up and opt in. Email signups without opt-in are not triggered by this action.
Default payload:
{
"site_id": "1",
"email": "person-40728a5b940e3247@talkable-sample.com",
"email_optin": "true"
}
Sync phone opt-ins¶
This action automatically synchronizes all people whenever they sign up and opt in for text messages. Signups without phone opt in are not triggered by this action.
Default payload:
{
"site_id": "1",
"email": "person-fa8e880e25bd47b3@talkable-sample.com",
"phone_number": "+12025551111"
}
Sync loyalty actions¶
This action automatically synchronizes all loyalty members whenever they make a loyalty action.
Default payload:
{
"site_id": "1",
"email": "loyalty@talkable.com"
}
Sync loyalty tier transitions¶
This action automatically synchronizes all loyalty members whenever their tier is changed.
Default payload:
{
"site_id": "1",
"email": "loyalty@talkable.com"
}
Unsubscribe¶
Whenever customers unsubscribe from Talkable emails they will also become unsubscribed in your ESP.
Default payload:
{
"site_id": "1",
"email": "person-591542c54ff21a49@talkable-sample.com"
}
Send reward¶
This action sends the reward information to your ESP.
Default payload:
{
"description": "$5",
"amount": "5.0",
"coupon_code": "FR_NEW_5_OFF",
"reason": "click",
"site_id": "1"
}
Create coupon¶
When the quantity of available coupons drops below a Talkable threshold this action sends you information.
Default payload:
{
"site_id": "1",
"coupon_code": "SAMPLE-COUPON-CODE",
"coupon_discount_amount": "0.0"
}
Event¶
Triggers when a new event or purchase is created.
Default payload:
{
"site_id": "1",
"type": "Event",
"created_at": "2024-11-25 00:00:00 -0800",
"event_category": "public_event",
"event_number": "183247241",
"subtotal": "100.0",
"currency_iso_code": "USD",
"email": "advocate@example.com"
}
Referral status change¶
This action is triggered when referral’s status changes.
Default payload:
{
"site_id": "1",
"campaign_id": "142",
"referral_status": "in_progress",
"advocate_email": "advocate@example.com",
"friend_email": "friend@example.com"
}
Click reward verification¶
This action sends information about a Friend when they attempt claiming a reward. The response from the Endpoint URL is checked to decide if a reward should be given. To reject unverified rewards, use click_reward_verified liquid variable in the incentive criteria.
Note: By default, the verification request times out at 1 second, and in that case the reward is considered verified.
Default payload:
{
"email": "friend@example.com",
"site_id": "1"
}
Testing¶
Testing Custom app actions can be accomplished with the help of Webhook Tester, an external service that tests your post-receive messages.
Visit Webhook Tester and click Copy to copy the URL you are given.
Open your Custom app.
Paste your Webhook Tester URL into Endpoint URL field and save.
Click Send sample payload near the action you want to test.
After you finish the implementation on your site change Webhook Tester URL to the live URL in your Custom app.
Click Send sample payload to test action with Live URL.
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:
|
|
|
|