Webhooks

API Reference

Integrations

Webhooks

Webhooks allow external systems to trigger actions in Intellia by making HTTP POST requests to webhook endpoints.

Overview

Webhooks in Intellia are incoming webhooks - they receive HTTP requests from external systems and execute configured handlers. Each webhook can have multiple handlers that process the incoming request data.

Handler Types:

agent - Execute an agent with the webhook data
action-chain - Run an action chain workflow

ℹ️

Webhook execution endpoints are publicly accessible (no authentication required). Use this for integrating with third-party services that need to trigger actions in Intellia.

Webhook Management

Create Webhook

POST /orgs/{organizationId}/webhooks

Required Role: Admin or Owner

Request Body:

{
  "name": "External System Webhook",
  "description": "Receives events from our CRM system"
}

Response:

{
  "webhookId": "webhook-123",
  "organizationId": "org-456",
  "name": "External System Webhook",
  "description": "Receives events from our CRM system",
  "creatorUserId": "user-789",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

List Webhooks

GET /orgs/{organizationId}/webhooks

Required Role: Admin or Owner

Query Parameters:

limit (optional): Number of results (default: 20)
cursor (optional): Pagination offset

Response:

{
  "items": [
    {
      "webhookId": "webhook-123",
      "name": "External System Webhook",
      "description": "Receives events from CRM",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalRows": 1,
  "offset": 0
}

Get Webhook

GET /orgs/{organizationId}/webhooks/{webhookId}

Required Role: Admin or Owner

Update Webhook

PUT /orgs/{organizationId}/webhooks/{webhookId}

Required Role: Admin or Owner

Request Body:

{
  "name": "Updated Webhook Name",
  "description": "Updated description"
}

Delete Webhook

DELETE /orgs/{organizationId}/webhooks/{webhookId}

Required Role: Admin or Owner

Permanently deletes the webhook and all its handlers.

Executing Webhooks

Execute Webhook

POST /orgs/{organizationId}/webhooks/{webhookId}/execute

Authentication: None required (public endpoint)

Request Body: Any JSON payload - this data will be passed to the handlers

Example:

{
  "event": "ticket_created",
  "ticketId": "TICKET-123",
  "priority": "high",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "subject": "Unable to login",
  "description": "Customer is getting error 500 when trying to login"
}

Response: Empty object {}

The webhook executes all configured handlers asynchronously. The response is returned immediately without waiting for handler execution.

Webhook Execution Context

Handlers receive a WebhookExecutionContext object containing:

{
  body: {}, // Request body as JSON
  headers: {}, // HTTP headers
  method: "POST", // HTTP method
  path: "/orgs/org-id/webhooks/webhook-id/execute", // Request path
  queryParams: {}, // Query parameters
  pathParams: {} // Path parameters
}

Webhook Handlers

Handlers define what actions to take when a webhook is triggered.

Create Handler

POST /orgs/{organizationId}/webhooks/{webhookId}/handlers

Required Role: Admin or Owner

Agent Handler Example:

{
  "handlerType": "agent",
  "agentId": "agent-123",
  "instructions": "Process the support ticket and create a response. Extract the ticket ID, priority, and customer information from the webhook data."
}

Action Chain Handler Example:

{
  "handlerType": "action-chain",
  "actionChainId": "chain-456",
  "instructions": "Process CRM event",
  "inputMapping": {
    "customerId": "{{body.customer.id}}",
    "ticketNumber": "{{body.ticketId}}",
    "priority": "{{body.priority}}"
  }
}

Response:

{
  "handlerId": "handler-789",
  "webhookId": "webhook-123",
  "organizationId": "org-456",
  "handlerType": "agent",
  "agentId": "agent-123",
  "agentName": "Support Agent",
  "instructions": "Process the support ticket...",
  "createdAt": "2024-01-01T00:00:00Z"
}

Handler Types

Agent Handler

Executes an agent with the webhook data. A new conversation is created for each webhook execution.

Required Fields:

handlerType: "agent"
agentId: ID of the agent to execute
instructions: Instructions for processing the webhook data

Behavior:

Creates a new conversation
Sends a message to the agent with webhook data and instructions
Agent processes the data and can use its tools
No user interaction possible (automated execution only)

Action Chain Handler

Runs an action chain workflow with mapped input data.

Required Fields:

handlerType: "action-chain"
actionChainId: ID of the action chain to run
instructions: Description of the handler purpose
inputMapping: Maps webhook data to chain input variables

Input Mapping:

Maps webhook context fields to action chain input variables using Handlebars syntax:

{
  "inputMapping": {
    "customerId": "{{body.customer.id}}",
    "customerEmail": "{{body.customer.email}}",
    "ticketId": "{{body.ticketId}}",
    "priority": "{{body.priority}}",
    "source": "{{headers.X-Source-System}}"
  }
}

Mapping Sources:

{{body.*}} - Request body fields
{{headers.*}} - HTTP headers
{{queryParams.*}} - Query parameters
{{pathParams.*}} - Path parameters

List Handlers

GET /orgs/{organizationId}/webhooks/{webhookId}/handlers

Required Role: Admin or Owner

Query Parameters:

limit (optional): Number of results (default: 20)
cursor (optional): Pagination offset

Get Handler

GET /orgs/{organizationId}/webhooks/{webhookId}/handlers/{handlerId}

Required Role: Admin or Owner

Update Handler

PUT /orgs/{organizationId}/webhooks/{webhookId}/handlers/{handlerId}

Required Role: Admin or Owner

Request Body:

{
  "instructions": "Updated instructions",
  "inputMapping": {
    "customerId": "{{body.customer_id}}"
  }
}

Delete Handler

DELETE /orgs/{organizationId}/webhooks/{webhookId}/handlers/{handlerId}

Required Role: Admin or Owner

Example Use Cases

CRM Integration

Scenario: When a support ticket is created in your CRM, trigger an Intellia agent to analyze it and suggest a response.

Setup:

Create webhook:

{
  "name": "CRM Support Tickets",
  "description": "Receives new support ticket events"
}

Create agent handler:

{
  "handlerType": "agent",
  "agentId": "support-agent-123",
  "instructions": "Analyze the support ticket from the CRM. Extract key information, categorize the issue, and draft a response for the support team. If the ticket is about billing, notify the billing team."
}

Configure your CRM to POST to:

https://api.intellia.com.au/orgs/your-org-id/webhooks/webhook-id/execute

E-commerce Order Processing

Scenario: When an order is placed, run an action chain to process it.

Setup:

Create webhook:

{
  "name": "Order Events",
  "description": "Receives order creation events from Shopify"
}

Create action chain handler:

{
  "handlerType": "action-chain",
  "actionChainId": "order-processing-chain",
  "instructions": "Process new e-commerce order",
  "inputMapping": {
    "orderId": "{{body.id}}",
    "customerEmail": "{{body.customer.email}}",
    "orderTotal": "{{body.total_price}}",
    "items": "{{body.line_items}}"
  }
}

Form Submissions

Scenario: Process form submissions from your website.

Setup:

Create webhook and agent handler
Add form submission endpoint to your website:

async function handleFormSubmit(formData) {
  const response = await fetch(
    'https://api.intellia.com.au/orgs/org-id/webhooks/webhook-id/execute',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        formType: 'contact',
        name: formData.name,
        email: formData.email,
        message: formData.message,
        submittedAt: new Date().toISOString()
      })
    }
  );
}

Security Considerations

Public Access

⚠️

Webhook execution endpoints are publicly accessible without authentication. Anyone with the webhook URL can trigger it.

Best Practices:

Keep URLs Secret - Treat webhook URLs like API keys
Validate Payload - Have handlers validate incoming data
Use HTTPS - Always use HTTPS for webhook URLs
Rotate URLs - If a webhook URL is compromised, delete and recreate
Monitor Usage - Review webhook execution logs regularly
Rate Limiting - Consider implementing rate limiting on your side

Validation in Handlers

For agent handlers, include validation instructions:

{
  "instructions": "IMPORTANT: First validate the webhook data. Check that required fields (ticketId, priority, customer.email) are present. If validation fails, log the error and do not proceed. Only process valid ticket data."
}

Troubleshooting

Common Issues

Issue	Solution
Webhook not executing	Verify webhook ID and organization ID in URL
Handler not running	Check handler exists and is properly configured
Agent handler fails	Review conversation logs for the created conversation
Action chain not starting	Verify action chain ID and input mapping
Invalid input mapping	Check field paths match webhook payload structure

Testing Webhooks

Use curl or Postman to test webhook execution:

curl -X POST \
  https://api.intellia.com.au/orgs/org-123/webhooks/webhook-456/execute \
  -H 'Content-Type: application/json' \
  -d '{
    "test": true,
    "message": "Testing webhook execution"
  }'

Debugging

Check Handler Configuration - Verify agent/chain IDs are correct
Review Input Mapping - Ensure paths match webhook payload
Test Payload Structure - Send test requests with various payloads
Monitor Conversations - For agent handlers, check created conversations
Action Chain Logs - For chain handlers, review chain execution logs

Limitations

Maximum 500 handlers per webhook
Handler execution is asynchronous (no response from handlers)
Public access only (no authentication on execute endpoint)
Agent handlers create new conversations (cannot append to existing)

Schedules