Inbound webhooks

Blue Reacher posts inbound messages to a URL you register on the workspace. There is one webhook per workspace, and it is part of the workspace record.

Register the URL

Set inbound_webhook_url when you create a workspace, or on an existing one with PATCH /v1/workspaces/{id}. The URL must be http(s).

Send inbound_webhook_headers with it: an array of { key, value } objects added to every delivery. Put a shared secret or an auth header here so your endpoint can tell a Blue Reacher delivery from anything else. Each entry needs a non-empty key.

curl -X PATCH https://api.bluereacher.com/v1/workspaces/7 \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_webhook_url": "https://your-app.example.com/inbound/messages",
    "inbound_webhook_headers": [
      { "key": "x-webhook-secret", "value": "your-shared-secret" }
    ]
  }'

Needs workspaces.write.

On POST /v1/workspaces the same two fields register the webhook in the same call. If the workspace is created but the webhook cannot be stored, the response is 200 instead of 201 and carries a warning field. Set the webhook again with PATCH.

Read the registration

GET /v1/workspaces/{id} includes an inbound_webhook object with the registered url and headers when one is configured. The field is omitted when none is.

{
  "success": true,
  "data": {
    "id": 7,
    "name": "Acme HQ",
    "inbound_webhook": {
      "url": "https://your-app.example.com/inbound/messages",
      "headers": [
        { "key": "x-webhook-secret", "value": "your-shared-secret" }
      ]
    }
  }
}

Validation errors

Deliveries

Each inbound message is an HTTP POST to your URL with a JSON body and the headers you registered. There is no signature header. Your registered header is how you authenticate a delivery, so use a long random value and compare it in constant time.

The body of a delivery is not documented on this page. Log the first delivery you receive and build your parser from it. Inbound messages also appear in GET /v1/messages with direction set to inbound and status received, so you can reconcile against the API at any time.

Answer with a 2xx quickly and do the work afterwards.

Outbound delivery status

There is no outbound status webhook. A send returns an id and the same value as the string message_id. Poll GET /v1/messages/{id} to follow the message from queued through webhook_sent, accepted, sent and delivered, or to failed. The status values are described in Key concepts.

Checklist

1. Register the URL and a secret header on every workspace you send from.
2. Reject any delivery whose secret header does not match.
3. Return a 2xx fast, then process.
4. Reconcile with GET /v1/messages if a delivery seems to be missing.