Webhook Plugin

Applications need to connect to other systems. When an order is placed, your fulfillment system must be notified. When a user signs up, a welcome email campaign starts. When inventory runs low, your purchasing team gets an alert in Slack.

The Ulabase Webhook plugin notifies external systems when an API request matches the conditions you specify.

The Integration Challenge

A reliable webhook system is harder to build than it looks. You need to intercept API requests in real time and decide which ones trigger a webhook. You need to transform the request data into the format the external system expects. You need to call the external endpoint, handle its failures and timeouts, log everything for debugging and compliance, and protect sensitive data in transit.

Each of these requirements takes work. Building such a system takes time, and maintaining it means dealing with edge cases, timeouts, and failures of the external systems.

Or you can use the Webhook plugin and start sending webhooks today.

How It Works

The Webhook plugin intercepts the requests to your Ulabase backend. When a request matches the conditions you specified, it sends an HTTP request to the endpoint you configured.

The Flow

  1. Request arrives at your backend (MongoDB APIs, GraphQL, WebSocket, or any other service)
  2. Condition evaluates using RESTHeart's predicate system
  3. Body transforms (optional) using Mustache templates to extract request data
  4. Webhook fires to your external endpoint
  5. Logs record the execution, while the webhook is recording, for debugging and compliance

Key Features

Flexible Triggers with Predicates

You define when a webhook fires with RESTHeart's predicate language. A condition can match specific HTTP methods, filter by request path, check field values, combine conditions with boolean logic, and use regex patterns.

Examples:

# Trigger on POST requests to /orders
method(POST) and path-prefix('/orders')

# Trigger on all POST and PATCH requests to orders
path-prefix('/orders') and (method(POST) or method(PATCH))

# Complex conditions with method and path
method(POST) and path-prefix('/users') and not(path('/users/me'))

With predicates you send a notification only for the requests that matter.

Body Transformation with Mustache

External systems often require data in a specific format. The Webhook plugin uses Mustache templates to reshape your request data into the format the external API requires.

Transform webhook bodies to match any API:

Input (Request data):

{
  "request": {
    "method": "POST",
    "path": "/orders",
    "body": {
      "_id": "order_123",
      "customer": {
        "name": "Alice Johnson",
        "email": "alice@example.com"
      },
      "items": [
        {"product": "Widget", "quantity": 2, "price": 29.99}
      ],
      "total": 59.98,
      "status": "pending"
    }
  }
}

Transformation Template:

{
  "order_id": "{{request.body._id}}",
  "customer_email": "{{request.body.customer.email}}",
  "customer_name": "{{request.body.customer.name}}",
  "order_total": "{{request.body.total}}",
  "order_status": "{{request.body.status}}",
  "item_count": "{{request.body.items.length}}"
}

Output (sent to webhook):

{
  "order_id": "order_123",
  "customer_email": "alice@example.com",
  "customer_name": "Alice Johnson",
  "order_total": "59.98",
  "order_status": "pending",
  "item_count": "1"
}

You can access nested properties with dot notation, restructure data to match external APIs, select only the fields you need, and format data for the webhook receiver, with no custom code.

Timeouts and Failures

Network failures happen, external services go down, and calls time out.

When a webhook call fails or times out, the failure is recorded in the log while the webhook is recording, and your own request is not affected. A failed call is not retried.

You define the timeout threshold (default 5000ms).

Comprehensive Logging

While a webhook is recording, every execution creates a detailed log entry. It shows the incoming request details, the condition evaluation result, the transformation input and output, the webhook request and response, the HTTP status code and timing, and the error message for a failed request.

Real-Time Testing with Recording

Building a webhook takes iteration. The plugin has a recording mode that captures live events for testing.

Start recording from the management interface and send requests to your API to generate events. Then select recorded events to test transformations, see a preview of the transformed data, and verify the webhook behavior before going live.

You test the transformation template with real data and see exactly what is sent.

Custom Headers Support

Many webhook receivers require authentication or custom headers. The plugin lets you configure any HTTP header for your webhook requests.

Common use cases:

Authorization: Bearer sk_live_abc123
X-API-Key: your-api-key-here
Content-Type: application/json
X-Webhook-Source: ulabase

Sensitive header values are stored securely and managed through the Ulabase interface.

Management Interface

The Webhook plugin includes a management interface to configure, test, and monitor webhooks.

Webhook Configuration

You create and edit webhooks with forms. You define the webhook name and target URL, specify trigger conditions with the predicate builder, configure the timeout, add custom headers including authentication, enable body transformation with Mustache templates, and preview the transformation results with real events.

Real-Time Preview

You test transformations before deployment: select recorded events from live traffic, view input and output side by side, validate the template syntax, and catch errors before the webhook goes live.

The preview shows both the original event data and the transformed output, so you can verify that your Mustache templates produce the expected results.

Log Analysis

The logs show the execution status (success, failed, skipped), HTTP response codes and timing, complete request and response bodies, transformation input and output, and error messages and stack traces. You can filter them by status and page through them.

Logs help you debug issues, meet audit requirements, and understand how the system behaves.

Recording Mode

To capture live events for testing, click "Record (60s)" to capture 60 seconds of events and generate test traffic to your API. Then select captured events for transformation testing and view the complete event data, including request details.

Recording mode is useful during development and when you modify existing webhooks. You test with real data without affecting live systems.

Real-World Use Cases

E-Commerce Order Fulfillment

Scenario: When customers place orders, your fulfillment center needs immediate notification.

Solution:

Condition: method(POST) and path('/orders')
URL: https://fulfillment.example.com/api/incoming-orders
Transformation: Map MongoDB order format to fulfillment system format
Headers: Authorization: Bearer [fulfillment-api-key]

Order requests flow from your storefront to fulfillment, with no manual process and no polling.

Slack Notifications for Critical Events

Scenario: Your team needs instant Slack alerts when deals are updated.

Solution:

Condition: method(PATCH) and path-prefix('/deals')
URL: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
Transformation: Format message for Slack with customer name, deal value, and sales rep

Your sales team sees notifications in real time. Use the transformation to filter high-value deals in the webhook body.

CRM Synchronization

Scenario: Keep your CRM in sync with customer data changes.

Solution:

Condition: path-prefix('/customers') and (method(POST) or method(PATCH))
URL: https://api.crm-system.com/v1/contacts/sync
Transformation: Map request data to CRM contact format
Headers: X-API-Key: [crm-api-key]

Customer data stays synchronized, with no manual export and import cycles.

Analytics Pipeline

Scenario: Feed user activity events into your analytics platform.

Solution:

Condition: path-prefix('/events')
URL: https://analytics.example.com/api/ingest
Transformation: Extract relevant fields and add metadata
Headers: Authorization: Bearer [analytics-token]

User behavior flows to your analytics system in real time.

Multi-System Integration

Scenario: One event needs to trigger multiple systems: inventory, shipping, accounting, and notifications.

Solution: Create multiple webhooks with the same condition, each targeting different systems with appropriate transformations.

Webhook 1: Inventory system
Webhook 2: Shipping provider
Webhook 3: Accounting software
Webhook 4: Customer notification service

One order placement triggers your entire backend workflow.

Configuration Example

This is a complete webhook configuration for order fulfillment:

Basic Settings:

  • Name: "Order Fulfillment Webhook"
  • URL: https://fulfillment.acme.com/api/orders
  • Timeout: 5000ms
  • Condition: method(POST) and path('/orders')

Headers:

Authorization: Bearer sk_live_abc123xyz
Content-Type: application/json
X-Webhook-Source: ulabase

Transformation Template:

{
  "external_order_id": "{{request.body._id}}",
  "customer": {
    "email": "{{request.body.customer.email}}",
    "name": "{{request.body.customer.name}}",
    "shipping_address": {
      "street": "{{request.body.shipping.street}}",
      "city": "{{request.body.shipping.city}}",
      "zip": "{{request.body.shipping.zip}}",
      "country": "{{request.body.shipping.country}}"
    }
  },
  "items": "{{request.body.items}}",
  "total_amount": "{{request.body.total}}",
  "currency": "{{request.body.currency}}",
  "created_at": "{{request.body.created_at}}"
}

This configuration watches for POST requests to the orders endpoint, transforms the request data to the fulfillment system's format, and includes authentication.

Get Started Today

Open your service in the console and go to Webhooks to create your first webhook. There is no infrastructure to build or maintain.

Contact us: sales@ulabase.com

Or visit the plugins page to learn more about all available plugins.

Build your app on Ulabase

Your backend is ready in minutes, and you spend your time on your app. The Free plan needs no credit card.