Webhook v2 vs v3
Discover the key differences between webhook v2 and v3 in NocoDB, including event model, payload enhancements, and new features.
NocoDB’s webhook system has evolved significantly in version 3, introducing a more streamlined structure, richer payloads, and enhanced configuration capabilities. This update reflects feedback from real-world usage and aims to simplify integration while giving users more control over what triggers a webhook.
Below is a detailed comparison of key changes between webhook v2 and v3.
Unified Event Model for Record Operations
In webhook v2, separate events were defined for individual and bulk operations—such as
- record.create, records.bulkCreate,
- record.update, records.bulkUpdate, and
- record.delete, records.bulkDelete.
This added complexity for consumers who needed to handle multiple event types for similar actions. Webhook v3 consolidates these into a simplified event model: after insert, after update and after delete. These events now apply uniformly to both single and bulk record operations.
Versioning in Webhook Payloads
Starting with v3, the webhook response includes a version identifier in the payload. This enables client systems to reliably parse and process webhook data based on the expected schema, and future-proof integrations as NocoDB continues to evolve its webhook capabilities.
Enhanced Payload for Bulk Insert Operation
Previously in webhook v2, the payload for bulk insert operations contained only the count of records that were inserted. This limited the ability to audit or react to specific insertions.
In v3, "After insert" webhook payload (unified for single insertion & bulk) includes the actual inserted records as an array. This enhancement allows integrators to trace exactly which records were inserted and take action accordingly—such as syncing insertions with external systems or logging for compliance.
New "Send Everything" Trigger Option
Webhook v3 introduces a "Send everything" trigger in the UI. This option allows users to configure a webhook that triggers on any change to records within a table—without having to specify individual event types. It's particularly useful when external systems need to stay in sync with all changes, regardless of whether they are inserts, updates, or deletes.
Field-Level Change Monitoring
Another key improvement in webhook v3 is the ability to configure field-specific triggers. This feature enables webhooks to fire only when certain fields are changed. For example, a webhook can be set to trigger only when the Status or Priority field is updated—helping reduce noise and streamline automation logic.
Summary
| Feature | Webhook v2 | Webhook v3 |
|---|---|---|
| Event Model | Separate events for bulk & single | Unified after insert/update/delete |
| Payload Version | Not available | Included in every webhook payload |
| Bulk Insert Payload | Only count of records | Full array of inserted records |
| Send Everything Trigger | Not available | Supported |
| Field Change Monitoring | Not supported | Supported |
Upgrade to webhook v3
If there are webhook v2 webhooks in your NocoDB instance, you will see a notification in the webhook list view. You can select the webhook that you want to upgrade to v3 and click on the Upgrade button. This will take you to the upgrade page where you can see the differences between the v2 and v3 webhook response. You can then click on the Upgrade button to upgrade the webhook to v3.
