Webhook Guide — Deal Flow for Mautic

Overview

Deal Flow supports two directions of webhook communication:

Inbound webhooks — external systems POST data to your Mautic® instance to create or update deals. Each source gets its own endpoint with a unique HMAC signing secret.
Outbound events — Deal Flow fires events through Mautic's native webhook system when deals change. Configure delivery in Mautic → Settings → Webhooks.

Inbound Webhooks

Inbound webhook sources are configured at Deal Flow → Settings → Inbound Webhooks. Each source has:

A unique URL endpoint under your Mautic instance
A per-source HMAC secret for request verification
A default pipeline assignment for new deals created via the source

Creating a Source

Go to Deal Flow → Settings → Inbound Webhooks
Click New
Name your source (e.g. "Typeform", "Website Contact Form")
Choose a default pipeline for inbound deals
Click Save

After saving, the source page displays the generated endpoint URL and signing secret. Copy the secret now — it will not be shown again in plaintext.

Endpoint URL

Each source gets a URL in the form:

Endpoint
POST https://your-mautic.com/deal-flow/settings/inbound-webhooks/{sourceId}/receive

HMAC Request Signing

All inbound webhook requests must include an HMAC-SHA256 signature. Deal Flow verifies this signature and rejects requests that fail verification.

Generating the Signature

Compute an HMAC-SHA256 hash of the raw request body using your source's signing secret, then include it in the X-DealFlow-Signature header.

PHP — Signature generation
$secret = 'your_source_secret';
$body   = json_encode($payload);
$sig    = 'sha256=' . hash_hmac('sha256', $body, $secret);

// Include in request header:
// X-DealFlow-Signature: sha256=abc123...

Node.js — Signature generation
const crypto = require('crypto');
const secret = 'your_source_secret';
const body   = JSON.stringify(payload);
const sig    = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

// Include in request header:
// X-DealFlow-Signature: sha256=abc123...

⚠️

Requests without a valid signature are rejected with HTTP 403. If you're testing with cURL or Postman, compute the signature from the exact body bytes you're sending — any whitespace difference will cause a mismatch.

Inbound Payload

The request body must be a JSON object. Deal Flow maps the following fields to deal properties:

JSON — Example inbound payload
{
  "title":      "Acme Corp - Enterprise Plan",
  "amount":     15000,
  "close_date": "2026-06-30",
  "contact": {
    "email":      "jane@acme.com",
    "first_name": "Jane",
    "last_name":  "Doe",
    "company":    "Acme Corp"
  },
  "custom_fields": {
    "source_system": "typeform",
    "form_id":       "abc123"
  }
}

The contact block is looked up by email in Mautic. If found, the existing contact is associated with the deal. If not found, a new Mautic contact is created.

Outbound Events

Deal Flow fires events through Mautic's native webhook dispatch system. Configure outbound webhook delivery in Mautic → Settings → Webhooks → New Webhook.

When configuring a Mautic webhook, you'll see Deal Flow events listed alongside Mautic's built-in events. Select the events you want delivered and specify your endpoint URL.

✓

Mautic's outbound webhook system handles retries, queuing, and delivery logging. Check Mautic → Settings → Webhooks for delivery logs.

Outbound Event Reference

These events are available for outbound webhook subscriptions:

dealflow.deal.created

A new deal was created

dealflow.deal.updated

A deal's fields were updated

dealflow.deal.stage_changed

A deal was moved to a new stage

dealflow.deal.won

A deal was moved to a "won" stage

dealflow.deal.lost

A deal was moved to a "lost" stage

dealflow.deal.contact_added

A contact was added to a deal

dealflow.deal.note_added

A note was added to a deal

dealflow.deal.task_completed

A task was marked complete

Outbound Payload Structure

JSON — Example outbound payload (stage changed)
{
  "event":     "dealflow.deal.stage_changed",
  "timestamp": "2026-03-25T14:30:00Z",
  "deal": {
    "id":        42,
    "title":     "Acme Corp - Enterprise Plan",
    "amount":    15000,
    "status":    "open",
    "stage": {
      "id":    7,
      "name":  "Proposal Sent",
      "type":  "open"
    },
    "pipeline": {
      "id":   1,
      "name": "Main Pipeline"
    }
  },
  "changed_by": {
    "id":   3,
    "name": "Sarah Johnson"
  }
}

Integration Examples

Typeform → Deal Flow

Use Typeform's webhook feature to send form submissions directly to Deal Flow as inbound webhook events. Map your form fields to the Deal Flow payload format in a middleware (e.g. Make.com, n8n, or a small Cloud Function).

Deal Flow → Slack

Subscribe to dealflow.deal.won in Mautic's outbound webhooks and point it at a Slack incoming webhook URL to get deal win notifications in Slack.

Deal Flow → CRM Sync

Subscribe to dealflow.deal.stage_changed and forward the payload to your external CRM's API to keep deal stages synchronized.