Webhooks
We POST an event to your endpoint when something happens to a link. Every request is signed so you can verify it came from us.
How it fits together
- Your CRM creates a link for a contact (
POST /v1/Services/{ServiceSid}/Links, a batch, or a contact import in the portal), using your own contact id asExternalUserId. - You send the link to the customer (WhatsApp, SMS, email).
- The customer opens it, reveals the reward and claims it. We POST
link.opened, thenlink.claimed(with the reward name), and laterlink.redeemedwhen it’s used. - Your endpoint verifies the signature and updates the contact found by
ExternalUserId.
Add an endpoint in the portal (Services, open your Service, then Webhooks) or with POST /v1/Services/{ServiceSid}/Webhooks. Use Test to send a ping, and the delivery log to see every event, its payload and your server’s response code, and to resend.
Events
| Event | When |
|---|---|
link.opened | The customer opened the link for the first time (sent once per link) |
link.claimed | The customer claimed the reward (sent once per link, includes RewardName) |
link.redeemed | The reward was redeemed (sent once per link). If opened/claimed weren’t sent yet, they are sent first. |
link.created | A link was created |
link.expired | A link passed its expiry date |
link.revoked | A link was revoked |
batch.completed / batch.failed | A batch, import or generated set finished |
recipient.erased | A recipient’s data was erased |
{
"EventType": "link.claimed",
"EventSid": "EV9f2c…",
"ApiVersion": "2026-11-01",
"AccountSid": "AC7f21…",
"ServiceSid": "RS2290…",
"LinkSid": "LKa81e…",
"CampaignSid": "CP4b07…",
"ExternalUserId": "crm_contact_1042",
"ExternalRef": "order-5521",
"RewardName": "₹500 Cashback Voucher",
"RewardType": "FLAT_AMOUNT",
"LinkStatus": "claimed",
"OccurredAt": "2026-11-12T10:42:07.000Z"
}Payloads carry ids, statuses and the reward name, never names, phone numbers or voucher codes, even for Services that store them.
Verify the signature
The X-EFIQ-Signature header is t=timestamp,v1=hex, an HMAC-SHA256 of {t}.{raw body} with your endpoint’s signing key. During a key rotation the header contains two signatures separated by a space; accept either. Reject timestamps older than 5 minutes.
import crypto from 'node:crypto';
export function verify(rawBody, header, signingKey) {
return header.split(' ').some((sig) => {
const { t, v1 } = Object.fromEntries(sig.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const mac = crypto.createHmac('sha256', signingKey).update(`${t}.${rawBody}`).digest('hex');
return mac.length === v1.length && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
});
}Retries
Answer with any 2xx within 10 seconds. Otherwise we retry after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours, then mark the event dead. You can replay any delivery from the delivery log (POST …/Deliveries/{EventSid}/Replay).