Use a signed inbound source for each external app
To create a deal in Mautic from an external app, map the app’s event into the documented JSON body, sign the exact serialized body with HMAC-SHA256, and POST it to a source-specific inbound URL. Give each integration its own inbound source and signing secret. Use middleware when the sender needs help transforming or signing data. Choose the REST API when an authenticated client needs targeted reads, updates by record ID, stage moves, or other explicit operations.
Deal Flow is a CRM plugin for Mautic focused on deals, pipelines, stages, tasks, and buying-committee context. Its inbound source combines a unique endpoint, its own request-verification secret, and a default pipeline for new deals. The public reference documents a compact deal-and-contact body, so the safest integration starts with those published fields and leaves undocumented selectors out.
Verified August 30, 2026 against the webhook overview, inbound-source setup, deal API reference, buying-committee contact operations, and task operations. Using middleware to sign is an implementation option that combines the documented mapping and HMAC steps.
Create one inbound source for each sender
Open Deal Flow → Settings → Inbound Webhooks in Mautic, then create a source with a recognizable name and choose its default pipeline. Saving the source produces its unique POST endpoint and HMAC signing secret.
- Name the sender. Use a label that identifies the form tool, billing system, or automation workflow responsible for the request.
- Select the default pipeline. The source uses that pipeline for new deals created through its endpoint.
- Save and capture the credentials. Copy the generated endpoint and secret when the source page displays them.
- Keep each integration separate. Send each app to its corresponding endpoint and sign with that source’s secret.
Capture the secret when it appears. The webhook reference says it will not be shown again in plaintext after the source is saved.
Source: Inbound Webhooks, verified August 30, 2026.
Sign the exact body sent to the endpoint
Every inbound request needs an HMAC-SHA256 signature. Compute the digest from the raw request body with the matching source secret, prefix the hexadecimal result with sha256=, and send it in the X-DealFlow-Signature header.
- Finish the JSON body. Serialize the final payload before computing the signature.
- Compute HMAC-SHA256. Use the exact raw body bytes and the secret assigned to this inbound source.
- Set the signature header. Send the prefixed digest in
X-DealFlow-Signature. - POST the same bytes. Do not reformat or serialize the body again after signing it.
Per-source signing keeps each sender on its corresponding credential. It also makes body integrity testable: even a whitespace change after signing produces a mismatch. Requests without a valid signature receive HTTP 403.
Source: HMAC Request Signing, verified August 30, 2026.
Map only the published inbound fields
The request body must be a JSON object. The served webhook reference publishes the following names; it does not label their requiredness, so keep validation assumptions out of the integration until you confirm them against the current reference.
| Published name | Documented shape | Documented behavior |
|---|---|---|
title | Top-level value | Shown as the deal title in the inbound example. |
amount | Top-level value | Shown as a numeric deal amount in the inbound example. |
close_date | Top-level value | Shown as a date string in the inbound example. |
contact | Object with email, first_name, last_name, and company | Email is used to find an existing Mautic contact; that contact is associated with the deal, or a new contact is created. |
custom_fields | Object | The example shows source_system and form_id entries. |
Do not invent an update selector. The overview says inbound requests can create or update deals, but the published payload section does not define an action field, deal identifier, or matching rule. This guide therefore does not prescribe one.
Source: Inbound Payload, verified August 30, 2026.
Use the same signed flow for different upstream systems
Form tool
Start with the submission event. Map its answers to the published deal and contact fields in middleware, serialize the body, sign it, and POST it to the form source’s endpoint. The served reference uses Typeform as its example.
Billing system
Treat the billing notification as the upstream event, then have a mapper build the same published deal body and sign it for the billing source. The served docs do not publish a billing-provider schema, so keep provider-specific fields in the mapper rather than adding them to the inbound contract.
Automation platform
As an implementation option, use an automation step to transform the upstream event, generate the signature over the final body, and send the request. The reference names Make.com and n8n as possible middleware.
Across all three patterns, the contract stays the same: one source-specific URL, one matching secret, the documented JSON shape, and the signature generated from the exact bytes sent.
Source: Integration Examples and HMAC Request Signing, verified August 30, 2026. Middleware signing and the billing pattern are implementation options assembled from the documented mapping and HMAC steps; the served docs name no billing provider or billing-specific payload.
Use the REST API for explicit record operations
Inbound sources fit event-driven intake: an external sender pushes a documented deal body to its signed endpoint. Use the REST API when a client already uses Mautic authentication and needs to identify, read, or change specific records through published operations.
| Need | Inbound source | REST API |
|---|---|---|
| Request verification | Per-source HMAC-SHA256 secret | Mautic authentication with appropriate Deal Flow permissions; Basic Auth and OAuth2 are documented |
| Create input | JSON object using the published inbound field names | Form POST with a required deal title and documented optional deal fields |
| Pipeline routing | Default pipeline assigned to new deals through the source | Pipeline and stage IDs are published create fields; list endpoints expose pipelines and stages |
| Targeted operations | The public payload section does not publish record-selection mechanics | Published routes cover list, view, update by deal ID, stage movement, contacts, notes, tasks, and batch actions |
For a deterministic update to a deal whose ID is known, the REST reference documents an update route that accepts the same fields as its create route and lets the client send only the fields it wants to change. It also documents a separate stage-move route and operations for buying-committee contacts, notes, and tasks.
Sources: API Authentication, Deals, Stages, Pipelines, Contacts, Notes, and Tasks, verified August 30, 2026.
Check the inbound path before using live events
- Create a separate source for each sending integration and record its matching endpoint and secret.
- Confirm the default pipeline intended for new deals from that source.
- Map only the field names published in the inbound payload reference.
- Finish serialization before signing, then send those exact raw bytes.
- Include the prefixed HMAC digest in
X-DealFlow-Signature. - Verify contact behavior with a representative email address.
- Use the documented REST operations when the workflow must address a known deal ID or perform a specific record action.
Technical references
All capability details on this page were checked against the served Deal Flow documentation on August 30, 2026:
- Webhook overview for inbound direction, unique endpoints, and per-source secrets.
- Inbound Webhooks for source setup, default pipeline assignment, and the generated secret.
- HMAC Request Signing for the digest, header, exact-body requirement, and HTTP 403 behavior.
- Inbound Payload for published field names and contact lookup behavior.
- API Authentication, Deals, Notes, and Tasks for authenticated record operations.
Add signed deal intake to Mautic
Deal Flow is a CRM plugin for Mautic focused on deals, pipelines, tasks, inbound webhook sources, and buying-committee context.
See Deal Flow Pricing Try free for 7 daysFrequently asked questions
What is an inbound webhook source in Deal Flow?
An inbound webhook source gives an external system a unique POST endpoint, a per-source HMAC secret, and a default pipeline for new deals created through that source.
How does HMAC signing work for inbound deal requests?
The sender computes HMAC-SHA256 over the exact raw request body with the source's secret and sends the result, prefixed with sha256=, in the X-DealFlow-Signature header. Missing or invalid signatures receive HTTP 403.
Which fields can an inbound deal payload contain?
The published inbound example covers title, amount, close_date, contact details, and custom_fields. Contact email is used to associate an existing Mautic contact or create a new one.
When should I use the REST API instead?
Use the REST API when an authenticated client needs explicit record operations such as listing or viewing deals, targeting a deal by ID for an update, moving stages, or managing contacts, notes, and tasks.
How does an inbound webhook choose a deal to update?
The public webhook reference says inbound requests can create or update deals, but it does not publish an update selector or matching rule. Check the current webhook reference before implementing updates, or use the documented REST update route when you know the deal ID.