Webhooks

Webhooks let you receive real-time notifications when events occur in your Rekall workspace. Subscribe to specific event types and receive HTTP POST requests to your endpoint with event details.

Overview

When you register a webhook endpoint, Rekall sends HTTP POST requests to your URL whenever subscribed events occur. Each delivery includes a JSON payload describing the event, along with a cryptographic signature you can use to verify the request originated from Rekall.

Webhook endpoints

Your webhook endpoint must respond with a 2xx status code within 30 seconds. The endpoint must be publicly accessible over HTTPS. Plain HTTP endpoints are not supported.

Scoping & management

Webhooks are hive-scoped: events for a hive are delivered to that hive's endpoints, and managing them (create/update/delete/test) requires a hive owner or admin role. Manage them via the API (an org-bound API key, or a browser session with the ?hive=/x-hive-id context) or in the dashboard under Hive workspace → Webhooks, which includes a delivery log and a test-fire button. The HMAC signing secret is shown once at creation.

Event Types

Subscribe to one or more of the following event types when creating a webhook.

Event	Description
`memory.created`	A new memory was created
`memory.updated`	An existing memory was updated
`memory.deleted`	A memory was deleted
`agent.spawned`	A new agent was spawned
`agent.completed`	An agent run completed
`decision.recorded`	A decision was recorded in the decision-context graph
`decision.outcome_recorded`	An outcome was recorded against a decision
`decision.proposal_submitted`	An agent submitted a decision proposal (HITL)
`decision.proposal_accepted`	A decision proposal was accepted
`decision.proposal_rejected`	A decision proposal was rejected
`gate.action_blocked`	The validation gate blocked an action

Webhook Payload

Every webhook delivery includes a consistent payload structure with the event type, timestamp, and the relevant resource data.

Example Payload

{
  "id": "evt_abc123def456",
  "type": "memory.created",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "id": "mem_xyz789",
    "type": "episodic",
    "content": "User completed onboarding flow",
    "context": "agent",
    "agent_id": "agent_abc123",
    "metadata": {
      "step": "onboarding_complete"
    },
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Signature Verification

Each webhook request includes an X-Rekall-Signature header containing an HMAC-SHA256 signature. Verify this signature to ensure the webhook was sent by Rekall and was not tampered with in transit.

The signature is computed using your webhook secret (provided when you create the webhook) and the raw request body.

Signature Verification (Node.js)

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf-8')
    .digest('hex');

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

// In your webhook handler:
app.post('/webhooks/rekall', (req, res) => {
  const signature = req.headers['x-rekall-signature'] as string;
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.REKALL_WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook event
  const event = req.body;
  console.log(`Received event: ${event.type}`);

  res.status(200).json({ received: true });
});

Always verify signatures

Never process webhook payloads without verifying the signature. Without verification, attackers could send fake events to your endpoint.

Delivery Lifecycle

Webhook deliveries go through the following states during their lifecycle:

Pending

Event is queued for delivery.

Delivering

HTTP POST request is being sent to your endpoint.

Delivered

Your endpoint responded with a 2xx status code within 30 seconds.

Failed

Delivery failed after all retry attempts have been exhausted.

Retry Policy

If your endpoint does not respond with a 2xx status code within 30 seconds, Rekall will retry the delivery with exponential backoff. The retry schedule is:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	24 hours

After 5 failed delivery attempts, the event is marked as failed. If a webhook endpoint consistently fails, it will be automatically disabled after 100 consecutive failures. You can re-enable it from the Developer Portal.

Webhook Management API

Use these endpoints to programmatically manage your webhook subscriptions.