Outly AI Webhooks

Verification code

Node.js

const crypto = require("crypto");

function verifyOutlyWebhook(secret, timestamp, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  const expectedBuf = Buffer.from(expected);
  const actualBuf = Buffer.from(signatureHeader);
  if (expectedBuf.length !== actualBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, actualBuf);
}

// In your route handler — use the RAW body string, before any JSON.parse:
app.post("/webhooks/outly", express.text({ type: "*/*" }), (req, res) => {
  const timestamp = req.header("X-Outly-Timestamp");
  const signature = req.header("X-Outly-Signature");

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return res.status(401).send("stale timestamp");

  if (!verifyOutlyWebhook(process.env.OUTLY_WEBHOOK_SECRET, timestamp, req.body, signature)) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(req.body);
  // ... idempotency check on event.id, then handle event.type ...

  res.status(200).send("ok");
});

Python

import hmac
import hashlib
import time

def verify_outly_webhook(secret: str, timestamp: str, raw_body: str, signature_header: str) -> bool:
    signed_content = f"{timestamp}.{raw_body}"
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), signed_content.encode("utf-8"), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# Flask example — use request.get_data() for the RAW body, never request.json first
@app.route("/webhooks/outly", methods=["POST"])
def outly_webhook():
    timestamp = request.headers.get("X-Outly-Timestamp")
    signature = request.headers.get("X-Outly-Signature")

    if abs(time.time() - float(timestamp)) > 300:
        return "stale timestamp", 401

    raw_body = request.get_data(as_text=True)
    if not verify_outly_webhook(OUTLY_WEBHOOK_SECRET, timestamp, raw_body, signature):
        return "invalid signature", 401

    event = request.get_json()
    # ... idempotency check on event["id"], then handle event["type"] ...

    return "ok", 200

curl (manual signature check while developing)

# Quick manual check against a payload you've already captured —
# not something you run against real Outly traffic, just useful while
# building your own verification code.
TIMESTAMP=1720000000
BODY='{"id":"evt_test","type":"test.webhook"}'
SECRET="whsec_..."

echo -n "${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$SECRET"

Security

• Outly only delivers to HTTPS endpoints in production, and validates + re-validates your URL server-side (including on every redirect hop) to block requests into private/internal networks.
• Deliveries never include OAuth tokens, API keys, or other credentials — only the minimal event data described above.
• Only POST is used. Outly never sends any other HTTP method to your endpoint.
• Workspace-level rate limiting protects against event bursts (e.g. a campaign generating thousands of events at once) — deliveries are capped and queued, never fired unbounded.

Troubleshooting

• Signature never matches: confirm you're signing the raw body string, not a re-serialized JSON.parse/JSON.stringify round-trip of it.
• Webhook marked "Unhealthy": your endpoint has failed 20 deliveries in a row. Check your logs, fix the issue, then use Send Test in Outly to confirm — a single success clears the unhealthy state.
• Not receiving events you expect: check the webhook's subscribed events list on its detail page, and confirm it's enabled, not disabled.