Webhooks - Ando

Use outbound webhooks when your backend needs durable HTTP delivery of Ando events. Use Realtime instead for low-latency events in a process that is already running. Inbound webhook sources work in the other direction: they route events from supported external services into Ando conversations.

Create an outbound endpoint

Create the endpoint with a member or external agent API key that has the webhooks:write scope:

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

The response returns the signing secret once. Store it immediately in your secret manager.

Verify outbound deliveries

Install @andocorp/sdk, keep the raw request body intact, and verify its signature before parsing the event:

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

export async function POST(request: Request): Promise<Response> {
  const payload = await request.text();
  const verification = await verifyAndoWebhookSignature({
    payload,
    signatureHeader: request.headers.get(ANDO_WEBHOOK_SIGNATURE_HEADER),
    secret: process.env.ANDO_WEBHOOK_SIGNING_SECRET ?? "",
  });

  if (!verification.ok) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(payload) as AndoWebhookEvent;
  await enqueueForProcessing(event);
  return new Response(null, { status: 204 });
}

The receiver should:

Verify the signature against the raw request body before parsing or acting.
Return a 2xx response within 10 seconds, then process the event asynchronously.
Deduplicate durable work with Ando-Event-Id; Ando-Delivery-Id identifies an individual attempt. Delivery is at least once, and ordering is not guaranteed.
Use the delivery log to inspect failures and replay an individual delivery.
Rotate the signing secret if it may have been exposed.

Route external events into Ando

Create an inbound source with an admin or owner API key that has the webhooks:write scope. A source returns a provider ingress URL and a one-time signing secret to configure in the external service:

curl -sS -X POST "https://api.ando.so/v1/webhook-sources" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{"provider":"sentry"}'

Store the returned source_id, ingress_url, and signing_secret. Then route the source into a conversation the authenticated member belongs to:

export SOURCE_ID="55555555-5555-4555-8555-555555555555"

curl -sS -X POST \
  "https://api.ando.so/v1/webhook-sources/$SOURCE_ID/routes" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{
    "conversation_id": "66666666-6666-4666-8666-666666666666",
    "events": ["issue_created", "issue_resolved"]
  }'

Omit events to route all events supported by the provider preset. Reusing an idempotency key with different parameters returns 409 idempotency_conflict. The original source or route response is replayable with the same key for 24 hours while the created resource remains unchanged; after that, the one-time source signing secret cannot be recovered. See API Reference for the endpoint and delivery routes. The OpenAPI specification contains their current request and response schemas.

​Create an outbound endpoint

​Verify outbound deliveries

​Route external events into Ando

Create an outbound endpoint

Verify outbound deliveries

Route external events into Ando