Webhooks Integration in Frappe Framework v15
Webhooks in Frappe Framework v15 enable real-time event-driven communication by sending HTTP requests to external systems when specific DocType actions occur.
This guide explains how to configure, secure, and manage webhooks in ERPNext and custom Frappe applications using the native webhook framework.
What Are Webhooks in Frappe?
Webhooks in Frappe are automated HTTP callbacks triggered when documents are created, updated, deleted, or submitted.
They allow external applications to receive structured JSON payloads instantly, without polling the Frappe server.
Common triggers include:
- After Insert
- On Update
- On Submit
- On Cancel
- On Delete
Why Use Webhooks in ERPNext & Frappe?
Webhooks are essential for modern integrations because they:
- Enable real-time data synchronization
- Eliminate periodic API polling
- Improve system responsiveness
- Reduce server load
- Support event-driven architecture
They are widely used in CRM, accounting, logistics, and manufacturing automation.
Target Audience
- ERPNext Integration Developers
- Frappe Backend Engineers
- Automation Specialists
- System Integrators
- SaaS Platform Architects
Technical Prerequisites
Before configuring webhooks, ensure:
| Requirement | Description |
| Framework | Frappe v15 |
| Access | System Manager role |
| Security | HTTPS enabled |
| Network | Public endpoint |
| Permissions | Webhook DocType access |
How Do Webhooks Work in Frappe v15?
Frappe webhooks are executed by the Webhook DocType and event handlers inside the framework.
Execution flow:
- DocType event occurs
- Webhook rule evaluated
- Payload generated
- HTTP request sent
- Response logged
- Retry logic applied
All operations are managed by frappe.integrations.webhook.
How to Configure Webhooks in Frappe v15 (Step-by-Step)
Step 1: Create a Webhook
Navigate to:
Desk → Webhook → New
Step 2: Configure Basic Settings
Fill the following fields:
| Field | Description |
| Webhook Name | Internal identifier |
| DocType | Trigger source |
| Request URL | Target endpoint |
| Enabled | Activate webhook |
Step 3: Select Event Triggers
Choose applicable events:
- After Insert
- On Update
- On Submit
- On Cancel
- On Delete
Multiple triggers may be selected per webhook.
Step 4: Configure Request Method
Supported methods in v15:
POST
PUT
POST is recommended for most integrations.
Step 5: Set Request Headers (Optional)
Example:
{
"Authorization": "Bearer your-token",
"Content-Type": "application/json"
}
Step 6: Define Payload Structure
Select one of:
- Send Full Document
- Send Specific Fields
- Custom JSON Payload
Example custom payload:
{
"name": "{{ doc.name }}",
"customer": "{{ doc.customer }}",
"status": "{{ doc.status }}"
}
Jinja templating is supported in v15.
Webhook Payload Example
{
"doctype": "Customer",
"name": "CUST-00025",
"customer_name": "ABC Industries",
"creation": "2026-01-30 10:15:00",
"owner": "admin@example.com"
}
Payloads are automatically serialized by Frappe.
How to Secure Webhooks in Frappe
Webhook security prevents unauthorized data interception.
Recommended measures:
- Use HTTPS endpoints
- Add Authorization headers
- Validate signatures (external)
- Whitelist IPs
- Rotate tokens
Frappe v15 does not generate HMAC signatures natively. Authentication is handled via headers.
Real-World Integration Example
ERPNext → Accounting Software Sync
Scenario: When a Sales Invoice is submitted, data is sent to an external accounting system.
Configuration:
| Setting | Value |
| DocType | Sales Invoice |
| Event | On Submit |
| URL | https://api.accounting.com/invoice |
| Method | POST |
Result: Automatic invoice synchronization.
Best Practices for Webhook Management
- Use dedicated integration users
- Keep payloads minimal
- Log responses regularly
- Implement retries externally
- Version endpoints
- Monitor failures
Common Issues & Troubleshooting
Webhook Not Triggered
Cause: Disabled rule
Fix: Enable webhook and reload cache
403 Forbidden Response
Cause: Missing auth header
Fix: Add valid Authorization token
Timeout Errors
Cause: Slow receiver endpoint
Fix: Optimize endpoint or use queue
Integration Patterns
Event-Driven Architecture
Frappe → Webhook → Message Broker → External Systems
Direct API Integration
Frappe → Webhook → SaaS Platform
Advanced: Webhooks with Background Workers
Enable Async Processing
Frappe processes webhooks via background jobs when configured.
Recommended for high-volume systems.
Custom Retry Logic (Server-Side)
frappe.enqueue(
"frappe.integrations.webhook.trigger_webhook",
webhook_name="Invoice Sync"
)
Use for controlled reprocessing.
Technical Categories & Tags
- Frappe Framework v15
- Webhooks Integration
- ERPNext Automation
- Event-Driven ERP
- API Connectivity
Summary
Webhooks in Frappe Framework v15 provide a reliable, real-time mechanism for synchronizing ERPNext data with external platforms.
By using native webhook rules, organizations can automate workflows, reduce latency, and build scalable integration pipelines.
