Webhook Events

Rekall fires webhook events for all significant actions across memories, entities, relationships, workflows, agents, and hives. Subscribe to the events your application needs in the dashboard.

Webhook setup

Configure webhook endpoints in your dashboard settings. You can filter which event types each endpoint receives.

Event Format

All webhook payloads follow a consistent envelope format. The type field identifies the event and the data field contains the event-specific payload.

Event Envelope
{
  "id": "evt_abc123def456",
  "type": "memory.created",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    // Event-specific payload
  },
  "metadata": {
    "api_version": "v1",
    "webhook_id": "wh_xyz789"
  }
}

Memory Events

memory.created

Fired when a new memory is created, regardless of memory type.

memory.created
{
  "id": "evt_m1a2b3c4d5",
  "type": "memory.created",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "memory_id": "mem_abc123",
    "memory_type": "episodic",
    "content": "User discussed project architecture decisions",
    "context": "agent",
    "agent_id": "agt_xyz789",
    "tags": ["architecture", "decisions"],
    "embedding_generated": true
  }
}

memory.updated

Fired when a memory is updated. Includes a diff of changed fields.

memory.updated
{
  "id": "evt_m2a3b4c5d6",
  "type": "memory.updated",
  "created_at": "2025-01-15T11:00:00Z",
  "data": {
    "memory_id": "mem_abc123",
    "memory_type": "episodic",
    "changes": {
      "content": {
        "previous": "User discussed project architecture decisions",
        "current": "User discussed project architecture decisions for the payments service"
      },
      "tags": {
        "previous": ["architecture", "decisions"],
        "current": ["architecture", "decisions", "payments"]
      }
    }
  }
}

memory.deleted

Fired when a memory is permanently deleted.

memory.deleted
{
  "id": "evt_m3a4b5c6d7",
  "type": "memory.deleted",
  "created_at": "2025-01-15T12:00:00Z",
  "data": {
    "memory_id": "mem_abc123",
    "memory_type": "episodic",
    "deleted_by": "usr_def456"
  }
}

Entity Events

entity.created

Fired when a new entity is added to the knowledge graph.

entity.created
{
  "id": "evt_e1a2b3c4d5",
  "type": "entity.created",
  "created_at": "2025-01-15T10:35:00Z",
  "data": {
    "entity_id": "ent_abc123",
    "name": "PaymentService",
    "type": "service",
    "properties": {
      "language": "TypeScript",
      "status": "active"
    },
    "context": "hive",
    "hive_id": "hiv_xyz789"
  }
}

entity.updated

Fired when entity properties or metadata are modified.

entity.updated
{
  "id": "evt_e2a3b4c5d6",
  "type": "entity.updated",
  "created_at": "2025-01-15T11:10:00Z",
  "data": {
    "entity_id": "ent_abc123",
    "changes": {
      "properties.status": {
        "previous": "active",
        "current": "deprecated"
      }
    }
  }
}

entity.deleted

Fired when an entity is removed. Associated relationships are also deleted.

entity.deleted
{
  "id": "evt_e3a4b5c6d7",
  "type": "entity.deleted",
  "created_at": "2025-01-15T12:05:00Z",
  "data": {
    "entity_id": "ent_abc123",
    "name": "PaymentService",
    "relationships_removed": 3
  }
}

Relationship Events

relationship.created

Fired when a new relationship is established between two entities.

relationship.created
{
  "id": "evt_r1a2b3c4d5",
  "type": "relationship.created",
  "created_at": "2025-01-15T10:40:00Z",
  "data": {
    "relationship_id": "rel_abc123",
    "source_entity_id": "ent_abc123",
    "target_entity_id": "ent_def456",
    "relationship_type": "depends_on",
    "weight": 0.85,
    "context": "hive",
    "hive_id": "hiv_xyz789"
  }
}

Workflow Events

workflow.triggered

Fired when a workflow run is initiated, either manually or by a trigger condition.

workflow.triggered
{
  "id": "evt_w1a2b3c4d5",
  "type": "workflow.triggered",
  "created_at": "2025-01-15T14:00:00Z",
  "data": {
    "workflow_id": "wf_abc123",
    "run_id": "run_xyz789",
    "name": "Deploy Pipeline",
    "trigger": "manual",
    "triggered_by": "usr_def456",
    "steps_count": 5,
    "status": "running"
  }
}

workflow.completed

Fired when a workflow run finishes. Includes duration and step completion summary.

workflow.completed
{
  "id": "evt_w2a3b4c5d6",
  "type": "workflow.completed",
  "created_at": "2025-01-15T14:15:00Z",
  "data": {
    "workflow_id": "wf_abc123",
    "run_id": "run_xyz789",
    "name": "Deploy Pipeline",
    "status": "completed",
    "duration_ms": 900000,
    "steps_completed": 5,
    "steps_failed": 0
  }
}

Agent Events

agent.spawned

Fired when a new agent instance is spawned from a husk definition.

agent.spawned
{
  "id": "evt_a1a2b3c4d5",
  "type": "agent.spawned",
  "created_at": "2025-01-15T09:00:00Z",
  "data": {
    "agent_id": "agt_abc123",
    "husk_id": "hsk_def456",
    "name": "ResearchBot",
    "capabilities": ["memories:read", "memories:write", "entities:read"],
    "context": "user",
    "user_id": "usr_xyz789"
  }
}

agent.terminated

Fired when an agent instance is terminated. Includes a summary of the session.

agent.terminated
{
  "id": "evt_a2a3b4c5d6",
  "type": "agent.terminated",
  "created_at": "2025-01-15T17:00:00Z",
  "data": {
    "agent_id": "agt_abc123",
    "husk_id": "hsk_def456",
    "reason": "completed",
    "memories_created": 42,
    "session_duration_ms": 28800000
  }
}

Hive Events

hive.member.added

Fired when a new member (user or agent) is added to a hive.

hive.member.added
{
  "id": "evt_h1a2b3c4d5",
  "type": "hive.member.added",
  "created_at": "2025-01-15T10:00:00Z",
  "data": {
    "hive_id": "hiv_abc123",
    "hive_name": "Engineering Team",
    "member_id": "usr_def456",
    "member_type": "user",
    "role": "member",
    "added_by": "usr_xyz789"
  }
}

hive.member.removed

Fired when a member is removed from a hive.

hive.member.removed
{
  "id": "evt_h2a3b4c5d6",
  "type": "hive.member.removed",
  "created_at": "2025-01-15T16:00:00Z",
  "data": {
    "hive_id": "hiv_abc123",
    "hive_name": "Engineering Team",
    "member_id": "usr_def456",
    "member_type": "user",
    "removed_by": "usr_xyz789",
    "reason": "role_change"
  }
}

Delivery & Retry

schedule

Retry policy

Failed deliveries are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, and 24 hours. After 5 failed attempts, the event is marked as failed and logged.

verified

Signature verification

All webhooks include an X-Rekall-Signature header containing an HMAC-SHA256 signature. Verify this against your webhook secret to ensure authenticity.

timer

Timeout

Your endpoint must respond with a 2xx status code within 30 seconds. Responses outside this window are treated as failures and trigger retries.

Idempotency

Webhook events may be delivered more than once. Use the id field to deduplicate events in your handler.

Rekall
rekall