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

  1. 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 as ExternalUserId.
  2. You send the link to the customer (WhatsApp, SMS, email).
  3. The customer opens it, reveals the reward and claims it. We POST link.opened, then link.claimed (with the reward name), and later link.redeemed when it’s used.
  4. 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

EventWhen
link.openedThe customer opened the link for the first time (sent once per link)
link.claimedThe customer claimed the reward (sent once per link, includes RewardName)
link.redeemedThe reward was redeemed (sent once per link). If opened/claimed weren’t sent yet, they are sent first.
link.createdA link was created
link.expiredA link passed its expiry date
link.revokedA link was revoked
batch.completed / batch.failedA batch, import or generated set finished
recipient.erasedA recipient’s data was erased
link.claimed (JSON format)
{
  "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.

Node.js
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).

Events can arrive more than once or out of order. Use the event id to ignore duplicates and the link status to decide what to do.