API Reference

Webhooks API

Complete API reference for configuring and managing webhooks for real-time event notifications.

Overview

Webhooks allow you to receive real-time HTTP notifications when events occur in your Engrami account. Configure endpoints to receive notifications for agent interactions, workflow completions, billing events, and more.

List Webhooks

GET /api/v1/webhooks

# Request
curl https://api.engrami.com/api/v1/webhooks?tenant_id=tenant_xyz \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "items": [
    {
      "id": "wh_abc123",
      "url": "https://your-app.com/webhooks/engrami",
      "events": ["agent.message", "workflow.completed"],
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Webhook

POST /api/v1/webhooks

# Request
curl -X POST https://api.engrami.com/api/v1/webhooks?tenant_id=tenant_xyz \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/engrami",
    "events": [
      "agent.message.created",
      "agent.message.completed",
      "workflow.execution.started",
      "workflow.execution.completed",
      "workflow.execution.failed"
    ],
    "secret": "your_webhook_secret_key",
    "metadata": {
      "environment": "production"
    }
  }'

# Response
{
  "id": "wh_def456",
  "url": "https://your-app.com/webhooks/engrami",
  "events": ["agent.message.created", "..."],
  "status": "active",
  "signing_secret": "whsec_abc123...",
  "created_at": "2024-01-20T10:30:00Z"
}

Available Events

Event	Description
agent.message.created	New message sent to agent
agent.message.completed	Agent finished processing
agent.created	New agent created
agent.updated	Agent configuration changed
workflow.execution.started	Workflow execution began
workflow.execution.completed	Workflow finished successfully
workflow.execution.failed	Workflow execution failed
memory.consolidated	Memory consolidation completed
billing.credits.low	Credits below threshold
billing.purchase.completed	Credit purchase successful

Webhook Payload

All webhook payloads follow a consistent structure:

{
  "id": "evt_abc123",
  "type": "agent.message.completed",
  "created_at": "2024-01-20T10:30:00Z",
  "data": {
    "agent_id": "agent_abc123",
    "conversation_id": "conv_xyz789",
    "message_id": "msg_def456",
    "content": "Here's how to reset your password...",
    "tokens_used": 245,
    "latency_ms": 1823
  },
  "tenant_id": "tenant_xyz",
  "api_version": "2024-01-01"
}

Signature Verification

Verify webhook authenticity using the signature header:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const timestamp = signature.split(',')[0].split('=')[1];
  const sig = signature.split(',')[1].split('=')[1];

  const signedPayload = `${timestamp}.${payload}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expectedSig)
  );
}

// Express middleware
app.post('/webhooks/engrami', (req, res) => {
  const signature = req.headers['x-engrami-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

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

  // Process webhook...
  res.status(200).send('OK');
});

Retry Policy

Failed webhook deliveries are automatically retried with exponential backoff:

Attempt 1: Immediate
Attempt 2: 1 minute delay
Attempt 3: 5 minutes delay
Attempt 4: 30 minutes delay
Attempt 5: 2 hours delay

After 5 failed attempts, the webhook is marked as failed and the endpoint may be disabled.

Test Webhook

Send a test event to verify your endpoint:

POST /api/v1/webhooks/{webhook_id}/test

# Request
curl -X POST https://api.engrami.com/api/v1/webhooks/wh_abc123/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "agent.message.completed"
  }'

# Response
{
  "success": true,
  "delivery_id": "del_xyz789",
  "response_status": 200,
  "response_time_ms": 234
}

Delivery Logs

GET /api/v1/webhooks/{webhook_id}/deliveries

# Request
curl https://api.engrami.com/api/v1/webhooks/wh_abc123/deliveries?limit=10 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "items": [
    {
      "id": "del_xyz789",
      "event_id": "evt_abc123",
      "event_type": "agent.message.completed",
      "status": "delivered",
      "response_status": 200,
      "response_time_ms": 234,
      "attempts": 1,
      "delivered_at": "2024-01-20T10:30:01Z"
    }
  ]
}

Continue to Slack Integration