frappe-webhook-manager_skill

Overview

This skill generates secure webhook receivers and outgoing webhook senders tailored for Frappe applications. It focuses on signing and verifying payloads, parsing events, and reliable delivery with retry and async processing. Use it to wire Frappe document lifecycle events to external systems or to accept notifications from third-party services. The goal is secure, maintainable, and testable webhook integrations.

How this skill works

The skill creates a guest-accessible webhook receiver that verifies HMAC signatures against a configured secret, parses JSON payloads, and dispatches event-specific handlers. For outgoing webhooks it provides helper functions to build payloads, enqueue asynchronous delivery, and implement retry and error logging. It uses Frappe configuration for secrets and target URLs, and leverages frappe.enqueue for background tasks to avoid blocking web requests.

When to use it

• Receiving event notifications from payment gateways, CRMs, or SaaS platforms.
• Sending document lifecycle events (submit, cancel, update) to external systems.
• Implementing event-driven integrations or webhooks in Frappe apps.
• Handling real-time updates that must be processed reliably and asynchronously.
• Securing endpoints with HMAC signatures to prevent spoofed requests.

Best practices

• Store webhook secrets and external URLs in frappe.conf, not in code or version control.
• Verify incoming requests using HMAC and constant-time comparison (hmac.compare_digest).
• Enqueue outbound webhooks for async delivery and implement retry with logging.
• Keep receivers idempotent: detect and ignore duplicate events to avoid side effects.
• Validate and sanitize payloads and restrict guest access to only the webhook route.

Example use cases

• Accept payment.success webhooks, validate signature, and mark invoices paid.
• Send invoice.submitted events to a fulfillment service when a Sales Invoice is submitted.
• Forward customer.updated events to a CRM and update local customer records.
• Integrate with a third-party analytics service by sending order events asynchronously.
• Build a secure webhook endpoint for a subscription billing provider to update subscription state.