Webhooks

Webhooks push events to your server when something happens on the line — for example a message is received or sent. Use them when you want real-time updates instead of polling GET /messages.

Building with the Messages API only? In the dashboard open Lines and choose API / webhooks (or claim a dedicated number with “Use API / webhooks”). That attaches the line to your account without a live no-code agent, so you do not get dual replies from both the agent and your webhook handler. You can also pause any existing agent on the line.

Prerequisites

A Messages API key with the comms_webhooks scope.
A public HTTPS URL that accepts POST.
Prefer API / webhooks inbound mode on Lines so no-code agents do not auto-reply alongside your backend.

Register an endpoint

curl -X POST "https://osis.co/api/v1/comms/webhooks" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.yourapp.com/comms",
    "events": ["comms.message.received", "comms.message.edited", "comms.message.reaction.added", "comms.message.sent"]
  }'

Scope: comms_webhooks
Success: 201 with the created webhook object, including its signing secret:

{
  "webhook": {
    "id": "1f0e9d8c-7b6a-4f5e-9d3c-2b1a0f9e8d7c",
    "url": "https://hooks.yourapp.com/comms",
    "events": ["comms.message.received", "comms.message.edited", "comms.message.reaction.added", "comms.message.sent"],
    "active": true,
    "secret": "whsec_…",
    "createdAt": "2026-08-04T19:45:00.000Z"
  }
}

webhook.secret is generated server-side on create — you never supply one. Store it wherever your handler runs; you’ll use it to verify every delivery. If you lose it, list webhooks returns it again for your endpoints. The Developers → Webhooks UI also reveals the secret immediately after create. Omitting events subscribes the endpoint to every comms event.

Which workspace gets the event?

Outbound webhooks are workspace-scoped: every matching event for lines owned by your org is delivered to your endpoints. There is no per-line webhook filter on the endpoint object. On a shared platform line, inbound traffic is routed to a workspace by claim keyword / sticky assignment for that contact. The org that owns the resolved route receives comms.message.* (and call/consent) events. Dedicated lines always belong to a single workspace. Every message event includes the line the contact reached (or that you sent from), when known:

Field	Meaning
`data.message.line_e164`	Your number on that thread (the inbound `to`)
`data.message.line_id`	Provider line id, for example `line_se_xxhtvk`

Use line_e164 as the tenant discriminator when one workspace owns more than one dedicated number. You do not need a dummy no-code agent per customer.

Message edit events

When a contact edits an iMessage, the messaging bridge emits message.edited (header X-Comms-Event: message.edited). Comms updates the stored message and fans out:

Outbound event	When
`comms.message.edited`	An inbound message body was updated after a bridge `message.edited`
`comms.poll.voted`	A contact voted on a native iMessage poll

Payload shape matches other message events, with extra fields on data.message:

{
  "event": "comms.message.edited",
  "object": "comms",
  "recordId": "msg_…",
  "data": {
    "message": {
      "id": "msg_…",
      "conversation_id": "conv_…",
      "contact_id": "sub_…",
      "direction": "inbound",
      "channel": "imessage",
      "line_id": "line_se_xxhtvk",
      "line_e164": "+16282646448",
      "body": "updated text",
      "previous_body": "original text",
      "status": "received",
      "created_at": "2026-08-04T19:45:00.000Z",
      "edited_at": "2026-08-04T19:46:12.000Z"
    },
    "contact": { "id": "sub_…", "phone": "+1…", "name": null },
    "conversation_id": "conv_…"
  },
  "sentAt": "2026-08-04T19:46:12.000Z"
}

Edits do not re-run the agent. Subscribe explicitly to comms.message.edited (or omit events to receive all).

Message reaction events

When a contact adds or removes a native iMessage tapback, the messaging bridge emits message.reaction (header X-Comms-Event: message.reaction). Comms stores the reaction on the target message and fans out:

Outbound event	When
`comms.message.reaction.added`	A love / like / dislike / laugh / emphasize / question tapback was added
`comms.message.reaction.removed`	That tapback was removed

{
  "event": "comms.message.reaction.added",
  "object": "comms",
  "recordId": "react_…",
  "data": {
    "reaction": {
      "id": "react_…",
      "message_id": "msg_…",
      "type": "love",
      "emoji": "❤️",
      "action": "added",
      "actor": { "kind": "contact", "handle": "+1…", "contact_id": "sub_…", "is_from_me": false }
    },
    "message_id": "msg_…",
    "conversation_id": "conv_…"
  }
}

Reactions do not re-run the agent. SMS cannot carry native tapbacks; outbound react calls return 409 unsupported_transport.

List endpoints

curl "https://osis.co/api/v1/comms/webhooks" \
  -H "Authorization: Bearer $COMMS_API_KEY"

Verify signatures

Every delivery is a POST with two headers:

Header	Value
`X-Osis-Event`	The event name, for example `comms.message.received`.
`X-Osis-Signature`	`sha256=<hex>` — an HMAC-SHA256 of the raw request body, keyed with your endpoint’s `whsec_` secret.

To verify: compute HMAC_SHA256(secret, rawBody), hex-encode it, and constant-time compare against the header value after stripping the sha256= prefix. Read the raw bytes before any JSON parsing — re-serialized JSON will not match.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyOsisSignature(rawBody: string, header: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = header.replace(/^sha256=/, "");
  if (received.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(received, "hex"), Buffer.from(expected, "hex"));
}

The payload envelope is the same for every event:

{
  "event": "comms.message.received",
  "object": "comms",
  "recordId": "msg_…",
  "data": { "message": { "…": "…" } },
  "sentAt": "2026-08-04T19:45:00.000Z"
}

Deliveries retry with exponential backoff (up to 6 attempts over ~1.5 days) and are marked dead after the final failure. The signature covers only the body — there is no signed timestamp — so treat delivery as at-least-once and dedupe on the event’s record id rather than relying on replay protection.

Send a test event

Fire a signed comms.ping at your endpoint without generating real traffic:

curl -X POST "https://osis.co/api/v1/comms/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $COMMS_API_KEY"

The ping goes through the same delivery pipeline as real events — same envelope, same signature — so a 2xx from your handler proves the whole path works. The test request waits for that attempt and returns its delivery status. The endpoint must include comms.ping in its events; otherwise the test returns an error immediately and does not enqueue a delivery.

Local development

Run your app with a POST handler that logs the body.
Tunnel with ngrok / Cloudflare Tunnel.
Register the tunnel URL as above.
Send a test message to your line, or fire a comms.ping with the test endpoint.

Handler checklist

Verify before trusting

Reject any request whose X-Osis-Signature doesn’t verify against your whsec_ secret. See Verify signatures.

Respond quickly

Return 2xx as soon as you accept the event. Do heavy work in a queue.

Treat delivery as at-least-once

The same event may arrive more than once. Make handlers idempotent on event id when present.

Keep secrets off the client

Webhook receivers belong on your server. Do not process hooks in a browser.

Create webhook
List webhooks
List events — poll delivery attempts if you need pull-based debugging

Introduction

Guides

Prerequisites

Register an endpoint

Which workspace gets the event?

Message edit events

Message reaction events

List endpoints

Verify signatures

Send a test event

Local development

Handler checklist

​Prerequisites

​Register an endpoint

​Which workspace gets the event?

​Message edit events

​Message reaction events

​List endpoints

​Verify signatures

​Send a test event

​Local development

​Handler checklist

​Related

Prerequisites

Register an endpoint

Which workspace gets the event?

Message edit events

Message reaction events

List endpoints

Verify signatures

Send a test event

Local development

Handler checklist

Related