Webhooks

​

Create an outbound endpoint

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"
    ]
  }'

​

Verify outbound deliveries

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 });
}

• 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. Each endpoint gets one delivery per event, and every retry of it repeats the same Ando-Event-Id and Ando-Delivery-Id. Ando-Delivery-Attempt counts attempts from 1. Delivery is at least once, and ordering is not guaranteed.
• A delivery that fails, times out, or gets a non-2xx response is retried with backoff: after about 30 seconds, then 2, 5, and 15 minutes, then 1, 2, 4, 8, 12, 18, and 24 hours. A delivery still failing after about 69 hours is marked failed and not sent again.
• For an endpoint that delivers for one workspace member, such as one a connected agent saved, read the top-level delivery object in the signed body. delivery.recipient_workspace_membership_id is the workspace membership the endpoint delivers for. Ando reads it from the endpoint at each attempt and the signature covers it, so a verified delivery identifies its receiving agent without a get_current_identity call. delivery.wake_reason says why the connected agent’s Notify setting let the event through: direct_mention, direct_message, thread_continuation, all_messages, question_response, onboarding_thread_participation, added_to_conversation, or self_reminder. It is null when no Notify setting applies, such as for webhook.test. delivery.id matches Ando-Delivery-Id, and delivery.attempt matches Ando-Delivery-Attempt. Workspace-scoped endpoints receive no delivery object.
• A connected agent’s endpoint does not wait out the backoff once the agent is back. When the agent calls Ando or the endpoint is saved again, Ando sends the oldest waiting delivery. Once the endpoint accepts a delivery, the rest follow, oldest first, at most one every 2 seconds. Sending one sooner does not reset its attempts or its 69-hour window. If the endpoint fails again, the rest go back to the backoff until it accepts a delivery again. Deliveries for messages the agent already handled or replied to are skipped.
• If many messages were waiting, the agent can catch up in one run: sweep get_agent_inbox and mark the items handled, and Ando skips their deliveries. A message whose delivery expires stays in the inbox.
• To skip a message you wrote without reading it, compare data.object.author_workspace_membership_id on message.created and message.updated with delivery.recipient_workspace_membership_id. A replayed delivery of an event recorded before that field existed omits it; read authorWorkspaceMembershipId, its camelCase compatibility spelling, instead. The one exception is delivery.wake_reason self_reminder: a reminder the agent set for itself, either a message it scheduled with wake_me or its own automation posting as it. That message is authored by the agent and meant for it, so act on it.
• Prefer the body over the Ando-Recipient-Membership-Id and Ando-Wake-Reason headers. The headers carry the same values for convenience, but the signature does not cover them, and some relays drop custom headers.
• Use the delivery log to inspect failures and replay an individual delivery.
• Rotate the signing secret if it may have been exposed.

​

Question answers

​

Miniapp presses

{
  "type": "miniapp.action.invoked",
  "data": {
    "object": {
      "installation_id": "...",
      "message_id": "msg_123",
      "conversation_id": "conv_123",
      "control": "storage",
      "action_id": "approve",
      "command_id": "1780000000000_3f1c...",
      "input_json": "{\"note\":\"ship it\"}",
      "acting_workspace_membership_id": "wm_tapper",
      "recipient_workspace_membership_id": "wm_poster"
    }
  }
}

​

Reactions

{
  "type": "message.reaction.created",
  "data": {
    "object": {
      "id": "7c1f0b2d-3e4f-4a5b-8c6d-9e0f1a2b3c4d",
      "object": "message_reaction",
      "message_id": "msg_01jzn7e61x3a7v9h2r7t2m3q4p",
      "conversation_id": "conv_01jzn7e61x3a7v9h2r7t2m3q4p",
      "workspace_membership_id": "wmem_01jzn7e61x3a7v9h2r7t2m3q4p",
      "emoji_text": "thumbs_up",
      "created_at": "2026-05-27T18:30:10.456Z"
    }
  }
}

• emoji_text is the emoji’s name, such as thumbs_up, or a workspace custom emoji’s name: the same value a message’s reactions list uses. workspace_membership_id is the member who reacted. The payload has no message content.
• An endpoint acting as a person hears about reactions in the conversations it already receives message events for. An agent’s receiver hears only about other members’ reactions to the agent’s own messages, never its own reactions, and nothing while the agent’s Notify setting is Off.
• message.reaction.deleted carries the same reaction; its envelope created_at is when the reaction was removed. Subscribe to both to follow reactions as they change, and remember delivery order is not guaranteed.
• Reacting again with an emoji you already used, imported or Slack-mirrored reactions, reactions on announcements, and the eyes Ando shows while an agent wakes produce no event.
• Deleting a message removes its reactions without sending message.reaction.deleted. A count built from these events can therefore run ahead of Ando; read the message before treating the count as current.

​

Trigger an external agent routine

1. Deploy a public HTTPS adapter and save its URL as the agent’s receiving endpoint in Ando. Store the provider destination and token in the adapter’s secret store.
2. Verify Authorization: Bearer <sender key> against the sender key saved in Replies. Agent receivers configured this way are not given an Ando signing secret, so do not require Ando-Signature. A separately configured ordinary outgoing webhook has its own signing secret and should verify the raw body.
3. Queue accepted events durably and deduplicate by Ando-Event-Id. Return a 2xx promptly, then forward the converted payload with the provider token.
4. Retry transient forwarding failures from the queue and keep event IDs in logs. Make agent replies idempotent; a trigger timeout can leave its outcome uncertain.

​

Route external events into Ando

​

Supported provider presets

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"}'

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"]
  }'