Webhooks

​

Reply

import express from "express";
import { Contiguity } from "contiguity";

const app = express();
const contiguity = new Contiguity();

app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
    if (!contiguity.webhook.verify(req, process.env.CONTIGUITY_WEBHOOK_SECRET)) {
        return res.sendStatus(401);
    }
    const event = contiguity.webhook.parse(req.body);
    if (event.type === "text.incoming.sms" || event.type === "text.incoming.mms") {
        await contiguity.text.reply(event, { message: "Got it, thanks!" });
    }
    if (event.type === "imessage.incoming") {
        await contiguity.imessage.reply(event, { message: "Hi back!" });
    }
    res.sendStatus(200);
});

import { Hono } from "hono";
import { Contiguity } from "contiguity";

const app = new Hono();
const contiguity = new Contiguity();

app.post("/webhook", async (c) => {
    const raw = await c.req.text();
    if (!contiguity.webhook.verify(raw, c.req.header("contiguity-signature"), process.env.CONTIGUITY_WEBHOOK_SECRET)) {
        return c.text("Invalid signature", 401);
    }
    const event = contiguity.webhook.parse(raw);
    if (event.type === "text.incoming.sms" || event.type === "text.incoming.mms") {
        await contiguity.text.reply(event, { message: "Got it, thanks!" });
    }
    if (event.type === "imessage.incoming") {
        await contiguity.imessage.reply(event, { message: "Hi back!" });
    }
    return c.text("ok", 200);
});

​

Verify

• rawBody: The exact raw request body (string or buffer). Never re-serialize JSON (e.g. do not use JSON.stringify(req.body)).
• signatureHeader: Value of the Contiguity-Signature header. Format: t=<timestamp>,v1=<hex>.
• secret: Your webhook signing secret.
• toleranceSeconds: Optional. If set (e.g. 300), rejects if |now - t| > toleranceSeconds.

​

Parse

​

Example

import { Contiguity } from "contiguity";
const contiguity = new Contiguity("contiguity_sk_..."); // or new Contiguity() for env

// In your route: use raw body only (e.g. express.raw for this route)
const raw_body = req.body; // buffer or string, unparsed
const ok = contiguity.webhook.verify(
  raw_body,
  req.headers["contiguity-signature"],
  process.env.WEBHOOK_SECRET,
  300
);
if (!ok) return res.status(401).send("Invalid signature");
const event = contiguity.webhook.parse(raw_body);
// event.id, event.type, event.timestamp, event.data

​

Payload format (v2)

• id: string (e.g. evt_...)
• type: string (event type)
• timestamp: number (Unix)
• api_version: string
• data: object (event-specific)

​

Signing reference

• Signed payload: t + "." + raw_body (timestamp t + . + raw body).
• Algorithm: HMAC-SHA256.
• Signature: hex-encoded in header as t=<t>,v1=<hex>.
• Verification: Compute HMAC-SHA256 of signed payload with webhook secret; compare to v1 with constant-time comparison. Optionally enforce timestamp tolerance (e.g. 300 seconds).