Skip to main content

​
Webhook Events

This page describes all available webhook events and their payload structures.

​
Event Types

​
Action Log Events

​
action_log.completed

Triggered when an action log completes successfully. Payload: 
{
  "event": "action_log.completed",
  "actionLog": {
    "id": "59ac65a5-33fe-43a6-924b-134c582a285e",
    "type": "MESSAGE",
    "status": "COMPLETED",
    "leadId": "4cc8af99-b313-4c1f-b98b-009f38a4721a",
    "summary": "Incoming email: docs",
    "input": {
      "channel": "EMAIL",
      "direction": "INBOUND",
      "metadata": {
        "agentMailData": {
          "to": ["Mark Ding <mark-local@agent.getomni.ai>"],
          "from": "Mark Ding <markdingkl@gmail.com>",
          "subject": "docs"
        }
      }
    },
    "output": null,
    "messages": [
      {
        "id": "2421bef7-95bc-4546-92a3-c7e5600fbb6a",
        "body": "<div dir=\"ltr\"><br></div>\n",
        "channel": "EMAIL",
        "subject": "docs",
        "direction": "INBOUND",
        "documents": []
      }
    ],
    "completedAt": "2025-10-30T20:07:17.553Z"
  },
  "occurredAt": "2025-10-30T20:07:17.567Z",
  "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c"
}

​
action_log.failed

Triggered when an action log fails. Payload: 
{
  "event": "action_log.failed",
  "occurredAt": "2025-10-30T21:12:45.123Z",
  "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c",
  "actionLog": {
    "id": "8f2b3f2a-9a3e-4f02-9f0d-1a2b3c4d5e6f",
    "type": "TOOL_CALL",
    "status": "FAILED",
    "summary": "Deep research failed",
    "input": {
      "toolType": "deep_research",
      "query": "market analysis for ACME"
    },
    "output": null,
    "error": "Upstream provider timeout after 5s",
    "completedAt": "2025-10-30T21:12:44.987Z",
    "leadId": "4cc8af99-b313-4c1f-b98b-009f38a4721a",
    "agentId": "c12d3456-7890-4abc-def1-234567890abc",
    "tool": {
      "id": "tool_123",
      "name": "deep_research"
    },
    "messages": []
  }
}

​
Document Events

​
document.received

Triggered when a document is received. Payload: 
{
  "event": "document.received",
  "document": {
    "id": "a80e6241-327f-419d-bae1-a4806d1a7641",
    "size": 153143,
    "leadId": "50713355-df73-4077-9d84-dcda6da5729c",
    "filename": "vital-checking-june-25.pdf",
    "metadata": null,
    "mimeType": "application/pdf",
    "createdAt": "2025-10-31T19:00:01.675Z",
    "messageId": "1ae4c028-ae4d-4e6d-aebd-cde96fdd8b3f",
    "signedUrl": "https://omniai-server-v2-dev.s3.us-east-2.amazonaws.com/..."
  },
  "occurredAt": "2025-10-31T19:00:01.700Z",
  "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c"
}

​
document.extracted

Triggered when document extraction completes. Payload: 
{
  "event": "document.extracted",
  "leadId": "910bb19a-2e9d-400f-8d15-9c461bb0f4aa",
  "status": "completed",
  "documentId": "ac52376a-fe68-4024-8b16-6acdcb9b3530",
  "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c",
  "parentActionId": "9d7fe2f3-ec1a-481c-b814-a0d1c8017e1f",
  "extractionResult": {
    "items": [
      {
        "label": "Company Name",
        "value": "OmniAI Technology Inc.",
        "leadChecklistItemId": "adc887d0-7238-4ce0-998d-523a22c282f4"
      },
      {
        "label": "Company Address",
        "value": "188 King St, San Francisco, CA, 94105",
        "leadChecklistItemId": "9930b10a-379d-4a83-be6a-9e16606c810c"
      }
    ],
    "extractedCount": 2
  }
}

​
Webhook Delivery

​
Request Format

Webhooks are sent as HTTP POST requests with:
  • Content-Type: application/json
  • Method: POST
  • Body: JSON payload containing the event data

​
Response Requirements

Your webhook endpoint should:
  • Return a 200 OK status code within 5 seconds
  • Handle requests asynchronously if processing takes longer
  • Return appropriate error codes for invalid requests

​
Retry Logic

If your endpoint doesn’t respond with a 200 status code, OmniAI will retry:
  • Initial retry: After 1 minute
  • Subsequent retries: Exponential backoff
  • Maximum retries: 3 attempts

​
Security

​
Webhook Secrets

For enhanced security, you can configure a webhook secret. OmniAI will include this secret in the webhook request headers, allowing you to verify request authenticity.

​
Best Practices

  • Use HTTPS endpoints only
  • Verify webhook signatures when possible
  • Implement idempotency to handle duplicate events
  • Set up retry logic for failed webhook deliveries
  • Monitor webhook delivery status

Webhooks User Guide

Learn how to set up webhooks

Create Webhook API

Create webhooks via API

List Webhooks API

List your webhooks