Reconcile Unsubscribe Webhooks Across Every Send System

An unsubscribe webhook is a signal to reconcile consent, not permission to overwrite every system blindly. A safe handler verifies the event, acknowledges it quickly, applies the most restrictive known status, and proves that every send-capable destination now excludes the address.

Editorial disclosure: Prepared by Marketing Wiki Research Automation under standing direct-publication authorization and not independently reviewed. Product capabilities are vendor-documented unless labeled otherwise; sources were refreshed on September 3, 2026.

Migma’s current webhook documentation says subscriber.unsubscribed can originate from one-click unsubscribe, mailto unsubscribe, dashboard status changes, or deletion. The payload includes an event ID, subscriber and project identifiers, email, action, and an optional source. Delivery is at least once, stops after three total attempts, and each attempt times out after ten seconds.

Those details create four separate questions: is the message authentic, have we processed this event ID, what consent change does the action represent, and have all send authorities converged?

Use a consent state that only moves toward safety#

For marketing eligibility, use a conservative precedence order:

complained / blocked > unsubscribed > unknown > subscribed

An unsubscribe event may move a contact from subscribed to unsubscribed. It must not move a complained, blocked, or previously suppressed contact back toward eligibility. A later profile update, CSV import, or CRM edit must not silently reverse the result.

Deletion needs its own policy. Migma documents the same event type for unsubscribe or deletion and provides an action field. Preserve that distinction in the consent ledger. Deletion may also trigger retention or erasure work; it is not merely another label for opt-out.

Reconciliation record#

Create one durable record per event before updating downstream systems:

Do not store a full webhook body in general-purpose logs if it exposes personal data unnecessarily. Retain only what the organization’s security, privacy, and audit policies require.

Handler contract#

1. Verify before parsing side effects. Validate the signature against the raw request body and reject stale or invalid deliveries according to the documented scheme.
2. Claim the event ID atomically. Insert the ID into a durable idempotency store. If it already completed, return success without repeating mutations.
3. Acknowledge quickly. Put accepted work on an internal queue and return 2xx; do not make Migma wait for every downstream vendor.
4. Resolve the subject in the correct project. Never use email alone when multiple brands or workspaces can contain the same address.
5. Apply restrictive precedence. Persist the consent ledger first, then fan out the effective state.
6. Retry destinations independently. A CRM outage must not cause a successful ESP suppression to be reversed or replayed as a subscription.
7. Close only after send authorities agree. Warehouses may lag, but every system capable of selecting or sending marketing email must exclude the contact.

Migma’s suppression-list documentation describes unsubscribed, complained, bounced, and manually blocked addresses as excluded from sends. That is the destination invariant to test. A webhook marked processed while one campaign tool can still select the contact is not reconciled.

Make replay safe without hiding failures#

Use an explicit state machine for each event ID:

received -> verified -> consent_recorded -> propagating -> reconciled
                    \-> rejected
                                   \-> needs_attention

Store destination attempts separately from the event. If the same webhook arrives while propagation is incomplete, return success after confirming the event is claimed, then let the internal retry worker continue. If your endpoint crashes before the durable claim, Migma’s retry can safely deliver it again.

Never mark an event complete merely because the webhook endpoint returned 2xx. That status only tells the sender the notification was accepted.

Test the failure paths#

Use non-production contacts and provider-supported test delivery to cover:

• the same event ID delivered twice;
• two different event IDs for the same address;
• an older subscribed update arriving after a newer unsubscribe;
• unsubscribe and deletion actions with and without a source;
• one destination timing out while another succeeds;
• an invalid signature and altered raw body;
• a handler that exceeds ten seconds;
• the same email in two project IDs;
• a later CSV import containing the unsubscribed address;
• a campaign query executed while reconciliation is incomplete.

The expected result is not “the webhook ran once.” It is “no replay, reorder, import, or partial outage restored marketing eligibility.”

Daily exception report#

Report events stuck outside reconciled, destinations with repeated failures, missing subscriber or project matches, actions your mapping does not recognize, and any contact that appears send-eligible after a restrictive event. Include event age and the next responsible owner. Do not include raw addresses in a broadly shared report; use controlled identifiers or redaction.

Evidence limits#

Marketing Wiki did not create a webhook, unsubscribe a real contact, inspect a signature, or test propagation into another vendor. Migma documents the event sources and delivery contract, but it does not establish how a reader’s CRM resolves consent conflicts, how long every destination takes to update, or which retention duties apply. Those remain organization-specific implementation and legal decisions.