Webhooks

Automate actions using webhooks in NocoDB

Webhooks allow you to trigger automated actions when specific events occur in your database. NocoDB supports flexible webhook configuration with conditions, custom payloads, and retry mechanisms.

Overview

Webhooks in NocoDB can be triggered by various database operations and can send data to external URLs or execute custom scripts. Each webhook can have filters, custom headers, and configurable retry logic.

Hook Events

Webhooks can be triggered by the following events:

• after.insert - Triggered after a new record is created
• after.update - Triggered after a record is updated
• after.delete - Triggered after a record is deleted
• after.bulkInsert - Triggered after multiple records are created
• after.bulkUpdate - Triggered after multiple records are updated
• after.bulkDelete - Triggered after multiple records are deleted
• manual - Triggered manually via API or button click

Webhook Configuration

Basic Properties

title · string · required

Name of the webhook

description · string

Description of what the webhook does

event · string · required

The event that triggers the webhook (e.g., “after”, “manual”)

operation · array · required

Operations that trigger the webhook: insert, update, delete, bulkInsert, bulkUpdate, bulkDelete

active · boolean · default: "true"

Whether the webhook is active

async · boolean · default: "true"

Whether to execute the webhook asynchronously

URL Webhooks

url · string

The endpoint URL to send webhook data to

headers · string

JSON string of custom headers to include in the request

{
  "Authorization": "Bearer YOUR_TOKEN",
  "Content-Type": "application/json"
}

Notification Integrations

notification · object

Configuration for notification services (Slack, Discord, Email, etc.)

{
  "type": "Slack",
  "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "channel": "#general"
}

Retry Configuration

retries · number · default: "0"

Number of retry attempts on failure (0-10)

retry_interval · number · default: "60000"

Interval between retries in milliseconds

timeout · number · default: "60000"

Request timeout in milliseconds

Conditional Triggers

condition · boolean · default: "false"

Whether to use filter conditions

Webhooks support filtering with conditions. You can add filters to only trigger the webhook when specific criteria are met.

trigger_field · boolean · default: "false"

Only trigger on specific field updates (for update operations)

trigger_fields · array

Array of column IDs that will trigger the webhook when updated

["col_abc123", "col_def456"]

Webhook Payload

Webhooks send a structured JSON payload containing event details and record data.

Payload Structure (v3)

type · string

Event type in format: records.after.{operation}

Example: records.after.insert

id · string

Unique event ID (UUID)

version · string

Payload version: v3

user · object

User who triggered the event (if available)

{
  "id": "usr_abc123",
  "email": "[e-mail]",
  "display_name": "John Doe"
}

data · object

Event data containing table information and records

data.table_id · string

ID of the table

data.table_name · string

Name of the table

data.rows · array

Array of affected records (for insert/delete operations)

data.previous_rows · array

Array of records before update (for update operations)

data.row_inserted · number

Number of rows inserted (for bulkInsert operations)

Example Payloads

After Insert

{
  "type": "records.after.insert",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "v3",
  "user": {
    "id": "usr_sample_user_id",
    "email": "[e-mail]",
    "display_name": "Sample User"
  },
  "data": {
    "table_id": "tbl_abc123",
    "table_name": "Users",
    "rows": [
      {
        "Id": 1,
        "Name": "Sample Text",
        "Email": "[e-mail]",
        "PhoneNumber": "0000000000",
        "Active": true,
        "CreatedAt": "2026-03-03T10:30:00.000Z"
      }
    ]
  }
}

After Update

{
  "type": "records.after.update",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "version": "v3",
  "data": {
    "table_id": "tbl_abc123",
    "table_name": "Users",
    "previous_rows": [
      {
        "Id": 1,
        "Name": "Old Name",
        "Email": "[e-mail]"
      }
    ],
    "rows": [
      {
        "Id": 1,
        "Name": "New Name",
        "Email": "[e-mail]"
      }
    ]
  }
}

After Bulk Insert

{
  "type": "records.after.insert",
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "version": "v3",
  "data": {
    "table_id": "tbl_abc123",
    "table_name": "Users",
    "row_inserted": 10
  }
}

Custom Payload Templates

You can customize webhook payloads using Handlebars templates:

{
  "text": "New record created: {{data.rows.0.Name}}",
  "user_email": "{{data.rows.0.Email}}",
  "timestamp": "{{data.rows.0.CreatedAt}}"
}

Filter Conditions

Webhooks support complex filter conditions:

• eq - Equals
• neq - Not equals
• like - Contains
• nlike - Does not contain
• gt / gte - Greater than / Greater than or equal
• lt / lte - Less than / Less than or equal
• empty / notempty - Is empty / Is not empty
• null / notnull - Is null / Is not null
• anyof / nanyof - Any of / None of
• allof / nallof - All of / Not all of
• checked / notchecked - Checkbox is checked / not checked

Best Practices

1. Use Async Webhooks: Enable async execution for better performance
2. Configure Retries: Set appropriate retry counts for critical webhooks
3. Add Filters: Use conditions to reduce unnecessary webhook calls
4. Monitor Logs: Check webhook logs to troubleshoot issues
5. Secure Endpoints: Always use HTTPS and authentication headers
6. Test First: Use the test webhook feature before activating
7. Field-Specific Triggers: For updates, only trigger on specific field changes to reduce noise

Webhook Versions

NocoDB currently uses webhook version v3, which provides:

• Multi-operation support (can trigger on multiple operations)
• Field-specific triggers for updates
• Improved payload structure
• Better performance and reliability

Webhook versions v1 and v2 are deprecated and not supported for new webhooks.