Smarter Contact API (1)

The people you text.

Conversation history and replies.

Add endpoints on the Webhooks tab of the Developer Platform page (up to 16), each subscribed to the events it needs.

Delivery: a POST with a JSON body. Any non-2xx answer, or no answer, is retried: up to 3 attempts in total, with backoff from 1 to 60 seconds. Answer 2xx fast and process later.

Every body also carries email (the account's email) and, for a test sent from the Webhooks tab, "test": true. Tell the events apart by the body: an incoming SMS has "direction": "incoming" and no event field, a status update has "event": "message.status_updated".

Headers: the custom headers you set on the endpoint are sent with every delivery.

Test deliveries from the Webhooks tab are sent once, with no retry, a 10 second timeout and no redirects followed.

Signature: when the account has a signing secret (Webhooks tab, starts with whsec_), each delivery has the header X-SC-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret>. Verify against the raw body bytes, not re-serialized JSON. t is set when the delivery is first queued and stays the same on every retry, so allow for the retry backoff when you check its age.

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && typeof v1 === 'string' && v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(expected, parts["v1"])