Webhooks

Receive real-time notifications when characters send proactive messages. Configure a webhook URL on your API key to get instant delivery.

Setup

Go to Profile > API Keys
Edit your API key and add a Webhook URL
Enable webhooks for the key
Use the "Test Webhook" button to verify your endpoint

Payload Format

When a character sends a proactive message, your webhook URL receives a POST request with this payload:

Webhook Payload

{
  "event": "proactive_message",
  "timestamp": "2024-01-15T14:30:00.000Z",
  "data": {
    "sessionId": "session_xyz",
    "characterId": "abc123",
    "characterName": "Mia",
    "message": {
      "id": "msg_456",
      "content": "Hey! I was thinking about what you said earlier...",
      "sentAt": "2024-01-15T14:30:00.000Z"
    }
  }
}

Signature Verification

Every webhook delivery includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Verify it to ensure the request came from us.

Node.js Verification

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    "your_webhook_secret"
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  // Process the webhook...
  const { event, data } = req.body;
  console.log(`New message from ${data.characterName}: ${data.message.content}`);

  res.status(200).send("OK");
});

Headers

Header	Description
X-Webhook-Signature	HMAC-SHA256 signature of the payload
X-Webhook-Event	Event type (e.g. "proactive_message")
X-Webhook-Timestamp	ISO timestamp of the event

Retry Policy

3 delivery attempts with exponential backoff
10 second timeout per attempt
Webhooks auto-disabled after 5 consecutive failures
Re-enable from your API Keys settings after fixing the issue