Documentation CRM Custom Webhook

CRM integration

Custom Webhook

  • CategoryCRM
  • AuthWebhook

Overview

The custom webhook receives JSON from an external form, CRM or other HTTP sender and delivers it to configured MessageMind automations. The request must carry the per-automation webhook token and contact data: a name plus at least one email or phone. An optional idempotency header collapses repeats inside the configured window. An unscoped URL only reaches automations whose secret matches the supplied token; it does not broadcast to every automation on the account.

What MessageMind can do with it

  • Accept a JSON object containing the required contact identity and expose its supported fields to the customWebhook automation trigger.
  • Dedupe transport retries by optional Idempotency-Key: a keyed call collapses retries inside a configurable window (ten minutes by default); the same key fires again in the next window.
  • Scope dedupe by target URL: one key sent to two automation-specific URLs and to the unscoped URL counts as three distinct events, so a single key never silently crosses automations.
  • Treat an authenticated, valid keyless call as a fresh delivery rather than deduplicating it. In-process callers that do not supply an idempotency key retain the same fresh-event behaviour.
  • Deliver goals first, then enrolments, so a running automation's goal step can observe the event before any new run it would start exists.
  • Record goal-endpoint receipts on the same ledger, keyed by automation, goal step and the key's hash per window, so the same key never completes the same goal step twice in a window.

Requirements

  • The ability to POST JSON to a URL from your external system.
  • At least one MessageMind automation listening on the customWebhook trigger, either scoped to a specific automation URL or discoverable through the unscoped URL.
  • The per-automation webhook token and a payload containing name plus at least one email or phone.

How to connect

  1. Open the automation you want to feed and copy its webhook URL and token. For an unscoped URL, only automations whose saved webhook secret matches that token are eligible.
  2. Configure the external system to POST a JSON object to that URL. Send the token in X-Webhook-Token; the token query parameter is accepted as a fallback.
  3. Optionally send a stable logical-event identifier in the Idempotency-Key header (X-Idempotency-Key or X-Webhook-Id are also accepted). A body field is not read as the idempotency key by this endpoint.
  4. Include name and at least one email or phone. Optional customFields entries use key/value pairs; map fields to the shape your automation expects.

Authentication and permissions

Mechanism
The per-automation webhook secret is required in X-Webhook-Token, with the token query parameter accepted as a fallback. User and automation IDs identify the destination; they are not sufficient authentication. There is no HMAC body signature. Idempotency headers control deduplication only.
Credentials
The webhook token saved for the target automation. Keep it private; the unscoped URL only matches automations using that supplied secret.

Available data and actions

Reads

  • The JSON body of each call: top-level name, email, phone and customFields array, plus the optional idempotency key, routed through the matched (or specified) automationId.

Writes

  • Contacts: each call creates or merges a contact from the body's name, email, phone and customFields.
  • Entity ledger marks: one claim per keyed call inside its window (entityId is sha1 of 'automationId or all' + newline + key, occurrence is the epoch-aligned window), or a fresh anonymous entity per keyless call.
  • Automation triggers: the customWebhook trigger fires with { fieldData, contactInfo, automationId } (or automationIds for the unscoped URL's matched set) as the envelope.

AI agent use cases

  • Wire any form builder, landing page or Zap-style tool that supports outbound webhooks to a MessageMind automation without a custom integration.
  • Trigger a MessageMind campaign from an internal tool (an ops dashboard, a CSV importer, a product event) by POSTing JSON to the automation's URL.
  • Use a stable external record id as the idempotency key so a flaky caller's retries inside ten minutes collapse to one enrolment, while the same record genuinely re-firing in the next window still runs.
  • Complete a goal step from an external system by POSTing to the automation's goal endpoint with the same key, so the same event never completes the same goal twice in a window.

Configuration

  • Idempotency window: ten minutes by default, overridable via the CUSTOM_WEBHOOK_IDEMPOTENCY_WINDOW_MS environment variable.
  • Window alignment: windows are aligned to the epoch, not to the time of the first call.
  • Scope: a key is hashed against the automation URL ('all' is used for the unscoped URL). The same key sent to two automation-specific URLs produces two distinct ledger entities.
  • Retention: entity ledger marks are kept a day, which covers the ten-minute window and every realistic retry of a delivery.
  • Keyless calls: a missing or whitespace-only key is treated as no key. Keyless calls are never deduped.
  • Delivery order: goals are offered the event before any run the enrolment starts exists.
  • Fail-open ledger: if the ledger cannot take the claim, the call still goes through and the event is recorded once by the emit path.

Example workflows

A keyed external event starts an automation once per window

  1. The external system POSTs a JSON body to the per-automation webhook URL with an Idempotency-Key that is a stable id for the logical event.
  2. MessageMind claims the entity (sha1 of automationId + newline + key, occurrence is the current window) before any contact write; a byte-identical or retried call inside the same window stops here as a duplicate.
  3. The contact is created or merged from the body's name, email, phone and customFields.
  4. The automation's goal steps observe the event first, then every active run listening on the customWebhook trigger is enrolled, with the envelope available for tokens.
  5. A later retry inside the window answers success: duplicate without a second contact write or a second enrolment. The same key sent in the next window fires again.

Limitations

  • The webhook verifies a token rather than an HMAC body signature. Protect the automation token and update the external sender when that token changes.
  • Dedupe only works for calls that carry an Idempotency-Key. Without a key every retry fires again.
  • Keyed dedupe is scoped to its window (ten minutes by default). A caller that resends the same key more than once per window still fires once per window, not once ever.
  • The custom webhook is inbound only. MessageMind does not call out to the external system; outbound integrations use the vendor-specific connectors.
  • The payload must include name and at least one email or phone. Optional custom fields use key/value pairs; unsupported nesting must be mapped into the expected shape.

Troubleshooting

The same external event enrolled a contact twice.

Either the caller omitted the Idempotency-Key (keyless calls never dedupe) or the second call arrived in a new window. Include a stable key and, if the retry gap is longer than ten minutes, raise CUSTOM_WEBHOOK_IDEMPOTENCY_WINDOW_MS.

A call succeeded but no automation started.

Confirm the automation is active, its saved token matches X-Webhook-Token (or the token query parameter), and the payload includes name plus email or phone. An unscoped URL only selects automations with the matching secret.

A retry answered success: duplicate but you expected a fresh run.

The Idempotency-Key collided with an earlier call inside the current window. Change the key when the logical event is different, or wait for the next window.

The goal step did not complete.

Goal receipts dedupe by automation, goal step and the key's hash per window. A different key, a different goal step or the next window all go through.

Disconnect and reconnect

  • Remove the webhook URL from the external system; MessageMind will stop receiving the calls immediately.
  • In the MessageMind dashboard, regenerate the automation's webhook URL to invalidate any URL still held by an external system.
  • Contacts already created from custom-webhook calls are kept; disconnecting does not remove them.