Webhook Events

Receive real-time notifications about messages, conversations, and contacts.

How Webhooks Work

When an event occurs in your Oryn account, we send a POST request to your configured webhook URL with a JSON payload describing the event. Your server should respond with a 200 status code within 10 seconds.

If your endpoint fails to respond, we retry with exponential backoff up to 5 times over 24 hours.

Event Types

Event	Description
`message.received`	An inbound message was received from a contact.
`message.status_updated`	An outbound message status changed (sent, delivered, read, failed).
`conversation.created`	A new conversation was created.
`conversation.assigned`	A conversation was assigned to an agent or team.
`contact.updated`	A contact record was created or updated.

Example Payloads

message.received

json

{
  "event": "message.received",
  "timestamp": "2026-04-10T14:30:00Z",
  "data": {
    "id": "msg_abc123",
    "conversation_id": "conv_xyz789",
    "contact": {
      "id": "ct_def456",
      "name": "John Doe",
      "phone": "+1234567890"
    },
    "type": "text",
    "content": {
      "text": "Hi, I need help with my order"
    },
    "channel": "whatsapp"
  }
}

message.status_updated

json

{
  "event": "message.status_updated",
  "timestamp": "2026-04-10T14:31:00Z",
  "data": {
    "id": "msg_out001",
    "conversation_id": "conv_xyz789",
    "status": "delivered",
    "previous_status": "sent"
  }
}

conversation.created

json

{
  "event": "conversation.created",
  "timestamp": "2026-04-10T14:28:00Z",
  "data": {
    "id": "conv_xyz789",
    "contact": {
      "id": "ct_def456",
      "name": "John Doe"
    },
    "channel": "whatsapp",
    "status": "open"
  }
}

conversation.assigned

json

{
  "event": "conversation.assigned",
  "timestamp": "2026-04-10T14:32:00Z",
  "data": {
    "id": "conv_xyz789",
    "assigned_to": {
      "id": "agent_abc",
      "name": "Sarah Chen"
    },
    "assigned_by": "auto_routing"
  }
}

contact.updated

json

{
  "event": "contact.updated",
  "timestamp": "2026-04-10T14:35:00Z",
  "data": {
    "id": "ct_def456",
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "tags": ["vip"],
    "changes": ["email", "tags"]
  }
}

Signature Verification

Every webhook request includes an X-Oryn-Signature header. This is an HMAC-SHA256 hash of the request body, signed with your webhook secret. Always verify the signature to ensure the request is authentic.

Node.js verification example

import crypto from 'crypto';

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}