Custom Webhook Integration

Push events from any external system into your workspace using a secure API key. No OAuth flow required.

Setup

Go to Admin → Integrations → Custom / API → Connect
Enter a name for the integration (e.g. “My App Webhook”)
Optionally enter an outbound webhook URL — where Berlay should POST agent replies back to your app
Click Connect — your API key is shown once. Copy it immediately.

Your integration is live. Use the inbound webhook URL and API key shown on the connect screen.

Inbound webhook

Send a POST request to push messages into Berlay. Each unique conversationId becomes a separate thread. Reusing a conversationId adds to an existing thread.

Endpoint

POST https://api.berlay.app/api/webhooks/custom/{channelId}

Headers

Header	Required	Value
Content-Type	Yes	application/json
x-berlay-api-key	Yes	Your channel API key (brly_...)

Body parameters

Field	Type	Required	Description
messageId	string	Yes	Unique ID for this message. Used for deduplication.
conversationId	string	Yes	Groups messages into a thread. Reuse to add to an existing conversation.
from.externalId	string	Yes	Stable identifier for the sender in your system.
from.name	string	No	Display name of the sender.
from.email	string	No	Email address — used to match or create a contact.
content	string	Yes	Message body text.
contentType	string	No	text (default) or html.
subject	string	No	Conversation subject. Only used on the first message of a thread.
sentAt	string	No	ISO-8601 timestamp. Defaults to time of receipt.

Example request

http

POST https://api.berlay.app/api/webhooks/custom/123
Content-Type: application/json
x-berlay-api-key: brly_a1b2c3d4...

{
  "messageId": "msg_01j9xk",
  "conversationId": "session_abc123",
  "from": {
    "externalId": "user_42",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "subject": "Need help with my order",
  "content": "Hi, I placed an order yesterday but haven't received a confirmation email."
}

Response

http

HTTP/1.1 200 OK

"ok"

The endpoint always returns 200 OK — even on validation failures — to prevent webhook retry storms. Check the channel event log (Admin → Integrations → [your integration] → Recent Events) for per-event delivery status.

Outbound webhook (agent replies)

When an agent replies to a conversation from a custom integration, Berlay sends a POST request to your configured outbound webhook URL (if set).

Payload

json

{
  "conversationId": "session_abc123",
  "content": "Hello Jane! I can see your order — a confirmation email is on its way."
}

If no outbound webhook URL is configured, agent replies are stored in Berlay but not forwarded.

API key security

Keys are stored as SHA-256 hashes — Berlay never stores plaintext
The plaintext key is shown once: at creation time and after regeneration
To rotate: Admin → Integrations → [your integration] → Regenerate
Regeneration immediately invalidates the previous key
All transport is over HTTPS

Event log

Every inbound request is logged with the following fields:

Field	Values
status	ok \| signature_failure \| skip \| routing_error
eventType	Event classification
error	Error message if status is not ok
createdAt	Timestamp

Access logs at Admin → Integrations → [your integration] → Recent Events.