Webhooks

Learn how to manage webhooks in NocoDB using the API

Webhooks allow you to trigger external services when specific events occur in your NocoDB tables. You can configure webhooks to fire after insert, update, or delete operations.

List Table Hooks

Retrieve all webhooks configured for a specific table.

GET /api/v1/db/meta/tables/{tableId}/hooks

curl -X GET "https://app.nocodb.com/api/v1/db/meta/tables/{tableId}/hooks" \
  -H "xc-auth: YOUR_API_TOKEN"

tableId · string · required

Unique Table ID

list · array

Array of hook objects

id · string

Unique Hook ID

title · string

Hook Title

event · string

Event type: after, before, manual, view, or field

operation · array

Array of operations: insert, update, delete, or trigger

active · boolean

Whether the hook is active

notification · object

Hook notification configuration including type, payload, method, body, headers, and path

fk_model_id · string

Foreign Key to Model/Table

async · boolean

Whether the hook executes asynchronously

retries · number

Number of retry attempts (default: 10)

retry_interval · number

Retry interval in milliseconds (default: 60000)

timeout · number

Timeout in milliseconds (default: 60000)

Create Table Hook

Create a new webhook for a table.

POST /api/v1/db/meta/tables/{tableId}/hooks

curl -X POST "https://app.nocodb.com/api/v1/db/meta/tables/{tableId}/hooks" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Webhook",
    "event": "after",
    "operation": ["insert"],
    "notification": {
      "type": "URL",
      "payload": {
        "method": "POST",
        "body": "{{ json data }}",
        "headers": [{}],
        "parameters": [{}],
        "path": "https://webhook.site/your-webhook-id"
      }
    },
    "active": true,
    "async": false,
    "retries": 10,
    "retry_interval": 60000,
    "timeout": 60000
  }'

tableId · string · required

Unique Table ID

title · string · required

Hook Title

event · string · required

Event type: after, before, manual, view, or field

operation · array · required

Array of operations: insert, update, delete, or trigger

notification · object · required

Hook notification configuration

type · string

Notification type (e.g., URL)

payload · object

Payload configuration with method, body, headers, and path

active · boolean

Whether the hook is active (default: true)

async · boolean

Whether the hook executes asynchronously

description · string

Hook description

retries · number

Number of retry attempts (default: 10)

retry_interval · number

Retry interval in milliseconds (default: 60000)

timeout · number

Timeout in milliseconds (default: 60000)

trigger_field · boolean

Whether this hook only triggers when specific fields are affected

trigger_fields · array

Array of field IDs that trigger this hook

Update Hook

Update an existing webhook.

PATCH /api/v1/db/meta/hooks/{hookId}

curl -X PATCH "https://app.nocodb.com/api/v1/db/meta/hooks/{hookId}" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Webhook",
    "active": false
  }'

hookId · string · required

Unique Hook ID

Delete Hook

Delete a webhook.

DELETE /api/v1/db/meta/hooks/{hookId}

curl -X DELETE "https://app.nocodb.com/api/v1/db/meta/hooks/{hookId}" \
  -H "xc-auth: YOUR_API_TOKEN"

hookId · string · required

Unique Hook ID

Test Hook

Test a webhook configuration before saving it.

POST /api/v1/db/meta/tables/{tableId}/hooks/test

curl -X POST "https://app.nocodb.com/api/v1/db/meta/tables/{tableId}/hooks/test" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hook": {
      "title": "Test Webhook",
      "event": "after",
      "operation": ["insert"],
      "notification": {
        "type": "URL",
        "payload": {
          "method": "POST",
          "body": "{{ json data }}",
          "path": "https://webhook.site/your-webhook-id"
        }
      }
    },
    "payload": {
      "data": {
        "Id": 1,
        "Title": "Sample Text",
        "CreatedAt": "2023-03-03T10:03:06.484Z"
      }
    }
  }'

tableId · string · required

Unique Table ID

hook · object · required

Hook configuration to test

payload · object · required

Sample payload to send to the webhook

Get Sample Hook Payload

Get a sample payload for webhook testing based on table schema.

GET /api/v1/db/meta/tables/{tableId}/hooks/samplePayload/{event}/{operation}/{version}

curl -X GET "https://app.nocodb.com/api/v1/db/meta/tables/{tableId}/hooks/samplePayload/after/insert/v3" \
  -H "xc-auth: YOUR_API_TOKEN"

tableId · string · required

Unique Table ID

event · string · required

Hook event: after, before, manual, view, or field

operation · string · required

Hook operation: insert, update, delete, or trigger

version · string · required

Hook version: v1, v2, or v3

includeUser · string

Include user information in sample payload (“true” or “false”)

List Hook Logs

Retrieve execution logs for a specific hook.

GET /api/v1/db/meta/hooks/{hookId}/logs

curl -X GET "https://app.nocodb.com/api/v1/db/meta/hooks/{hookId}/logs" \
  -H "xc-auth: YOUR_API_TOKEN"

hookId · string · required

Unique Hook ID

list · array

Array of hook log objects

id · string

Unique Log ID

fk_hook_id · string

Foreign Key to Hook

event · string

Hook event type

operation · string

Hook operation

execution_time · string

Execution time in milliseconds

response · string

HTTP response from the webhook endpoint

payload · string

Payload sent to the webhook

error · string

Error message if the webhook failed

triggered_by · string

User who triggered the hook

test_call · boolean

Whether this was a test call

Webhook Payload Structure

When a webhook is triggered, NocoDB sends a POST request to the configured URL with the following structure:

v3 Payload Structure

{
  "type": "records.after.insert",
  "id": "hook-execution-id",
  "data": {
    "table_id": "md_abc123",
    "table_name": "TableName",
    "view_id": "vw_xyz789",
    "view_name": "ViewName",
    "rows": [
      {
        "Id": 1,
        "Title": "Sample Record",
        "CreatedAt": "2023-03-03T10:03:06.484Z",
        "UpdatedAt": "2023-03-03T10:03:06.484Z"
      }
    ]
  },
  "user": {
    "id": "usr_abc123",
    "email": "[e-mail]"
  }
}

Event Types

The type field follows this pattern: records.{event}.{operation}

• records.after.insert - After a record is inserted
• records.after.update - After a record is updated
• records.after.delete - After a record is deleted
• records.before.insert - Before a record is inserted
• records.before.update - Before a record is updated
• records.before.delete - Before a record is deleted

Using Webhook Data

You can use template variables in your webhook configuration:

• {{ json data }} - Full JSON payload
• {{ json data.rows }} - Array of affected rows
• {{ data.table_name }} - Table name
• {{ user.email }} - User email who triggered the action