entity_webhook

Entity Webhook provides configurable webhook ingestion and broadcasting for Drupal entities. Receive JSON payloads from external services to create or update content, and broadcast entity changes to external systems — all through an admin UI with no custom code required.

Features

Inbound Webhooks (Core Module)

• Receive JSON payloads at configurable endpoints (/webhook/{endpoint}/{source}) and automatically create or update Drupal entities (nodes, users, taxonomy terms, etc.)
• Extract values from payloads using JSONPath expressions (e.g., $.order.customer.email)
• Transform extracted values with mutation plugins: timestamp formatting, string/regex replace, value mapping, price conversion, JSON encoding, and array reshaping
• Composite key entity lookups — match incoming data to existing entities using one or more identifier fields
• Pluggable request verification: HMAC signature validation, API key authentication, and IP/domain whitelisting
• Queue-based async processing — webhooks are accepted immediately and processed during cron
• Pre-save and post-save events for custom logic via event subscribers

Outbound Webhooks (Broadcast Submodule)

• Watch entity create, update, and delete events on any entity type and bundle
• Filter which events trigger webhooks using Drupal's Condition API (e.g., only published nodes)
• Build structured JSON payloads from entity fields, including traversal of entity references
• HMAC request signing with configurable algorithm and shared secret
• Exponential backoff retry with configurable max attempts and base delay
• Delivery logging for auditing, debugging, and retry tracking

Scheduled Polling (Polling Submodule)

• Poll external APIs on a cron schedule using configurable cron expressions
• Feed polled data into the same processing pipeline as inbound webhooks
• SHA-256 hash-based change detection to skip unchanged records

Architecture

• Three-tier config entity hierarchy for both inbound and outbound: Endpoint → Source/Subscription → Field Mapping
• All configuration managed through Drupal's admin UI
• Pluggable at every layer: verification, value resolution, field mutation, polling providers, and outbound value resolvers

Post-Installation

1. Enable the module at /admin/modules. Enable only the submodules you need: Entity Webhook Broadcast for outbound webhooks, Entity Webhook Polling for scheduled API polling.
2. Configure inbound webhooks at /admin/config/services/webhooks:
   • Create a Webhook Endpoint — choose the target entity type (e.g., Node) and optional bundle.
   • Add a Source Type under the endpoint — configure verification (HMAC, API key, or domain whitelist) and set up field mappings with JSONPath expressions pointing into your expected payload structure.
   • Mark one or more field mappings as identifiers for entity lookup (upsert behavior).
   • Your webhook URL will be: https://yoursite.com/webhook/{endpoint_id}/{source_type_id}
3. Configure outbound webhooks at /admin/config/services/outbound-endpoints (requires Broadcast submodule):
   • Create an Outbound Endpoint — select the entity type, bundle, and which CRUD events to watch. Optionally add conditions to filter events.
   • Add a Subscription under the endpoint — provide the destination URL, HMAC signing settings, and retry configuration.
   • Add Field Mappings under the subscription to define the outbound JSON payload structure.
4. Configure polling at /admin/config/services/entity-webhook-polling (requires Polling submodule):
   • Create a polling configuration referencing an existing inbound Webhook Endpoint and Source Type.
   • Set a cron expression for the polling schedule and configure a polling provider plugin.
5. Process queues: Inbound and outbound webhooks are processed asynchronously during cron. Ensure cron is running regularly, or use a queue runner for near-real-time processing.

Additional Requirements

• PHP 8.3 or higher
• Drupal 10.3 or Drupal 11
• softcreatr/jsonpath (^0.8) — JSONPath expression parsing for extracting values from JSON payloads. Installed automatically via Composer.
• dragonmantank/cron-expression (^3.3) — Cron expression parsing for the Polling submodule. Installed automatically via Composer.

No additional Drupal contributed modules are required. The module depends only on Drupal core.

Recommended modules/libraries

• Automated Cron (core) or an external cron runner — ensures webhook queue items are processed promptly.
• Queue UI — provides a UI to inspect and manage queue items, useful for monitoring webhook processing.
• Advanced Queue — for more robust queue processing with job management, if your site handles high webhook volume.

Similar projects

• Feeds — imports content from external sources (RSS, CSV, XML). Entity Webhook is purpose-built for real-time JSON webhook payloads rather than batch feed imports, with built-in HMAC verification and outbound broadcasting.
• Hook Post Action — provides entity lifecycle hooks for triggering actions. Entity Webhook goes further with a complete outbound delivery system including retry logic, HMAC signing, and delivery logging.

Supporting this Module

If you find Entity Webhook useful, contributions are welcome! You can help by:

• Reporting bugs and feature requests in the issue queue
• Submitting patches or merge requests
• Writing documentation or tutorials