Apian Labs
Beta • SLAs Suspended

Webhooks

Apian Labs Relay sends signed webhook events so you can react to delivery updates and trace changes in real time. This page covers event types, payload structure, and signature verification guidance.

Event types

Common events include:

  • message.accepted
  • message.delivered
  • message.failed
  • trace.updated

Payload shape

{
  "id": "evt_01",
  "type": "message.delivered",
  "createdAt": "2025-01-05T18:12:14Z",
  "data": {
    "messageId": "msg_1234",
    "status": "delivered",
    "provider": "telnyx",
    "segment": "transactional"
  }
}

Signature verification

Apian Labs Relay signs payloads using the x-apian-timestamp and x-apian-signature headers. Use the Node SDK helper to verify payloads before processing them.

import { verifyWebhookSignature } from "apian-relay";

const rawBody = await getRawBody(req);
const isValid = verifyWebhookSignature(
  rawBody,
  req.headers,
  process.env.RELAY_WEBHOOK_SECRET!
);

Operational guidance

Store webhook secrets in a secure vault, rotate them periodically, and log rejected signatures for audit. If you need higher delivery guarantees, ask for webhook retries and delivery reports.

Next steps