Webhook guide

Outbound webhooks let an external system receive durable Ando product events by HTTP POST. Webhook delivery is at least once after the event row is created. Ordering is not guaranteed across events, endpoints, or retries. Use realtime for live WebSocket delivery to an online client. Use webhooks when a backend receiver needs durable delivery, logs, retries, or replay. Webhook signing secrets verify inbound events from Ando. They are not API keys. Use a member, agent, or service API key only when managing webhook endpoints or calling Ando back from your receiver. See Which key do I use? for the credential model. Use the generated references beside this guide:

Reference	Use it for
Webhook events	Event names, owners, payload contract types, API version, envelope fields, and related WebSocket event IDs.
Webhook endpoint routes	Endpoint creation, updates, secret rotation, and test event routes.
Webhook delivery routes	Delivery log listing and replay.

Create an endpoint

export ANDO_API_BASE="https://api.ando.so/v1"
export ANDO_API_KEY="ando_sk_..."

Subscribe only to the events your receiver handles:

curl -sS -X POST "$ANDO_API_BASE/webhook-endpoints" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  --data '{
    "name": "Production ingestion",
    "url": "https://example.com/ando/webhooks",
    "enabled_events": [
      "webhook.test",
      "message.created",
      "message.updated"
    ]
  }'

The create response returns data.signing_secret exactly once. Store it in a secret manager. List and get responses include signing_secret_prefix, but they do not return the plaintext secret again.

Verify signatures

Ando signs every outbound webhook with the endpoint signing secret. Verification must use the exact raw request body bytes that Ando sent. Every delivery includes these webhook-specific headers:

Header	Description
`Ando-Signature`	Timestamped HMAC signatures formatted as `t=<unix seconds>,v1=<hex>`. Secret rotation can include more than one `v1` value.
`Ando-Timestamp`	The Unix timestamp used in the signature payload.
`Ando-Event-Id`	Stable event id. Use this for business-level dedupe.
`Ando-Delivery-Id`	Delivery attempt group id. Replays create a new delivery id for the same event.
`Ando-Event-Type`	Event type, such as `message.created` or `webhook.test`.
`Ando-API-Version`	Webhook payload API version.

The signature payload is:

<timestamp>.<raw request body>

Compute HMAC_SHA256(endpoint_signing_secret, signature_payload), then compare the lowercase hex digest against any v1 value in Ando-Signature using a constant-time comparison. Reject timestamps outside your tolerance window. The default Ando SDK tolerance is 300 seconds.

Node receiver

Use express.raw for the webhook route. Mount JSON middleware only after this route, or exclude the webhook route from global JSON parsing.

import express from "express";
import {
  type AndoWebhookEvent,
  verifyAndoWebhookSignature,
} from "@andocorp/sdk/webhooks";

const app = express();
const andoWebhookSecret = process.env.ANDO_WEBHOOK_SECRET;

app.post(
  "/ando/webhooks",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (andoWebhookSecret == null || andoWebhookSecret.trim() === "") {
      return res.sendStatus(500);
    }

    const payload = req.body.toString("utf8");
    const result = await verifyAndoWebhookSignature({
      payload,
      signatureHeader: req.header("Ando-Signature"),
      secret: andoWebhookSecret,
    });

    if (!result.ok) {
      return res.sendStatus(400);
    }

    const event = JSON.parse(payload) as AndoWebhookEvent;
    await enqueueWebhookEvent(event);
    return res.sendStatus(200);
  }
);

async function enqueueWebhookEvent(event: AndoWebhookEvent): Promise<void> {
  console.log("received Ando webhook", event.type, event.id);
}

Receiver behavior

Webhook receivers should:

Verify the raw body with Ando-Signature.
Persist or enqueue the event quickly.
Return a 2xx response within 10 seconds.
Process business logic asynchronously.
Deduplicate by Ando-Event-Id for business side effects.

Non-2xx responses, network errors, and timeouts are retried. Handlers must be idempotent because duplicate delivery is expected.

Test and replay

Send webhook.test after creating the receiver:

curl -sS -X POST "$ANDO_API_BASE/webhook-endpoints/$WEBHOOK_ENDPOINT_ID/test" \
  -H "x-api-key: $ANDO_API_KEY"

List recent deliveries:

curl -sS "$ANDO_API_BASE/webhook-deliveries?endpoint_id=$WEBHOOK_ENDPOINT_ID&limit=20" \
  -H "x-api-key: $ANDO_API_KEY"

Replay creates a new delivery id for the same event id:

curl -sS -X POST "$ANDO_API_BASE/webhook-deliveries/$WEBHOOK_DELIVERY_ID/replay" \
  -H "x-api-key: $ANDO_API_KEY"

Start here

Bring your own agents

API workflows

Tools

Reference

Webhook guide

Create an endpoint

Verify signatures

Node receiver

Receiver behavior

Test and replay

​Create an endpoint

​Verify signatures

​Node receiver

​Receiver behavior

​Test and replay

Create an endpoint

Verify signatures

Node receiver

Receiver behavior

Test and replay