Link your system

Link your system sends signed webhook events from Adraa Inbox to a URL you control, and lets your API act on them in the same HTTP response. When a customer asks “where is my order?”, your server can look the order up by the contact’s phone number and reply instantly — no flow required.

Connect your endpoint

An admin opens Settings → Link your system.
Enter your webhook URL (must be https:// and publicly reachable) and pick the events to send.
Click Connect and copy the signing secret (whsec_…) — it’s shown only once. Use Rotate later to issue a new one.
Click Send test event to deliver a sample message.received payload and inspect your server’s response.

Events

Event	Fires when
`message.received`	A customer message arrives on any channel (WhatsApp, Instagram, TikTok, email, web widget).
`conversation.created`	A new conversation starts.
`contact.created`	A contact first appears in the workspace.
`contact.updated`	An agent changes a contact’s fields or language.
`conversation.resolved`	A conversation is closed.
`conversation.assigned`	A conversation is assigned to an agent.

The request we send

Each event is a POST with a JSON body:

{
  "event": "message.received",
  "timestamp": "2026-07-02T10:00:00.000Z",
  "webhookId": "…",
  "company": { "id": "…", "name": "acme" },
  "contact": {
    "id": "…",
    "name": "Sara",
    "phone": "+9665xxxxxxxx",
    "email": null,
    "customFields": { "customer_tier": "gold" }
  },
  "conversation": { "id": "…", "channel": "whatsapp", "status": "open" },
  "message": { "id": "…", "text": "where is my order?", "attachments": [] }
}

conversation is omitted for contact.* events, message is present only on message.received, and assignment (agentId, agentName) is added on conversation.assigned. Test deliveries include "test": true.

Verify the signature

Every delivery carries these headers:

Header	Value
`X-Adraa-Event`	The event name.
`X-Adraa-Webhook-Id`	The endpoint’s id.
`X-Adraa-Timestamp`	Unix seconds when the request was signed.
`X-Adraa-Signature`	`sha256=` + HMAC-SHA256 of `"{timestamp}.{rawBody}"` using your signing secret.

verify-signature.js

import crypto from "crypto";

function isFromAdraa(req, rawBody, secret) {
  const timestamp = req.headers["x-adraa-timestamp"];
  const signature = req.headers["x-adraa-signature"];
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return (
    Boolean(signature) &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  );
}

Reject requests whose timestamp is more than a few minutes old to prevent replays.

Respond with actions

Return HTTP 200 with JSON. Any actions you include run immediately:

{
  "actions": [
    { "type": "reply", "text": "Order #1234 ships tomorrow 🎉" },
    { "type": "set_contact_fields", "fields": { "last_order_id": "1234" } },
    {
      "type": "set_context",
      "data": {
        "orders": [
          { "id": "1234", "status": "shipped", "total": "250 SAR" }
        ]
      }
    }
  ]
}

Action	What it does
`reply`	Sends `text` to the customer on the conversation’s channel, as an automated agent message.
`trigger_flow`	Runs the flow named by `flowId` on the conversation, with optional `variables`. WhatsApp conversations only.
`set_contact_fields`	Merges `fields` into the contact’s custom fields (the Metadata section of the contact panel).
`set_context`	Replaces the contact’s Linked system panel with `data` — structured business context like orders or bookings that agents see next to the conversation.

An empty body or {} is fine when you only want to record the event — for example, feeding an analytics pipeline.

Limits

Up to 5 actions per response, of which at most 3 replies (4,096 characters each).
fields is capped at 32 keys / 16 KB; data at 32 KB.
reply and trigger_flow are skipped on contact.* events (no conversation in scope).
Invalid actions are recorded in the delivery log; valid ones still run.

Delivery behavior

Deliveries are fire-and-forget: they never delay message processing, and a reply lands moments after the customer’s message. Your endpoint has 10 seconds to respond; non-2xx responses and timeouts are logged and ignored — there are no automatic retries, so a slow endpoint can’t double-message a customer. The Recent deliveries table in settings keeps the last 50 requests with response bodies and per-action results for debugging.

Example uses

Order status: reply with live order data looked up by phone number, and push the order list into the Linked system panel for agents.
CRM enrichment: on contact.created, tag the contact with tier and account owner from your CRM.
Dynamic routing: on message.received, trigger a VIP flow for customers your database marks as high-value.
Ticket sync: mirror conversation.created / conversation.resolved into Jira or Zendesk.

Prefer polling or building against the REST API instead? Everything the inbox exposes is also available on the public API, and no-code automations are covered by the Zapier integration.

Getting started

Guide

Channels

Inbox

Automation & AI

Integrations

Workspace

Connect your endpoint

Events

The request we send

Verify the signature

Respond with actions

Limits

Delivery behavior

Example uses

​Connect your endpoint

​Events

​The request we send

​Verify the signature

​Respond with actions

​Limits

​Delivery behavior

​Example uses

Connect your endpoint

Events

The request we send

Verify the signature

Respond with actions

Limits

Delivery behavior

Example uses