How outbound webhooks work in MegatronLead

Outbound webhooks are how MegatronLead notifies your systems when something happens. A lead arrives. A state transitions. An SLA breaches. A user is created. Each is an event that your downstream systems may want to act on.

The webhook mechanism is straightforward to use and operationally hardened. This is the technical overview.

What outbound webhooks are for

Three classes of use case:

Triggering downstream automation. When a lead reaches QUALIFIED, your system fires off a contract template. When a lead's market changes, your fulfillment system reassigns the account team.

Keeping external systems in sync. Your data warehouse needs every lead event. A real-time webhook feed keeps it current without polling.

Notifying internal tools. A custom Slack notification format, a JIRA ticket creation for compliance reviews, an email alert for VIP leads.

Each is event-driven. Webhooks let your system react in real time without polling MegatronLead's API.

Setting up a subscription

In the admin UI:

1. Go to Admin -> Outbound webhooks.
2. Create a subscription. Specify:
   • The endpoint URL on your side that will receive POSTs.
   • The signing secret (generate one, share via secrets manager).
   • The event types to subscribe to. Available types are documented and stable.
   • Optional filters (only leads in market X, only state changes to QUALIFIED).

Once active, MegatronLead POSTs each matching event to your endpoint with a signed body.

The same configuration is available via API.

The payload

Every webhook POST has:

• Headers including the signature, the event type, and a delivery ID.
• A JSON body containing the event metadata and the affected resource.

The body schema is documented per event type. Schema evolution is backward-compatible within an event-type version; major changes get a new version.

Signature verification

Before trusting the payload, your endpoint must verify the signature.

The signature is computed by MegatronLead as an HMAC-SHA256 of the request body using the shared secret. Your endpoint:

1. Reads the signature header.
2. Computes the same HMAC over the received body.
3. Compares using constant-time comparison.
4. If the signatures match, the payload is authentic. Process it.
5. If they do not match, reject the request (return 400 or 401).

Signature verification is non-negotiable. Without it, your endpoint cannot trust that the POST actually came from MegatronLead. An attacker who discovers your webhook URL could otherwise inject events.

The signing secret is shared between MegatronLead and your endpoint. Rotate it periodically; rotation is supported in the UI.

Replay protection

A replay attack is an attacker capturing a valid signed request and resending it. To defeat replay, MegatronLead includes a timestamp in the signed payload.

Your endpoint should:

• Verify the timestamp is recent (within a few minutes of current time).
• Optionally, deduplicate by delivery ID (each delivery has a unique ID; track seen IDs).

The combination prevents replayed requests from being processed twice.

At-least-once delivery

Webhooks are delivered at least once. Most events are delivered exactly once, but transient failures can produce retries that result in duplicate delivery.

Your endpoint must be idempotent: receiving the same event twice should produce the same outcome as receiving it once. Common patterns:

• Track delivery IDs and skip duplicates.
• Make the downstream action naturally idempotent (e.g., upsert by canonical lead ID).

A non-idempotent endpoint will eventually misbehave on retries.

Retries

If your endpoint returns a non-success status (anything other than 2xx) or fails to respond within the timeout, MegatronLead retries with exponential backoff:

• First retry: after 30 seconds.
• Second retry: after 2 minutes.
• Third retry: after 15 minutes.
• Subsequent retries with increasing intervals up to a maximum.

Retries continue for up to 24 hours. If the endpoint is still failing, the event is moved to the dead-letter queue.

This retry policy is designed to absorb your endpoint's transient downtime without losing events.

The dead-letter queue (DLQ)

Events that fail to deliver after the full retry sequence end up in the DLQ.

In the admin UI:

• View DLQ entries by subscription.
• Inspect the failure reason (last HTTP status, last response body, retry history).
• Manually replay individual entries after fixing the endpoint.
• Export the DLQ as CSV for bulk processing.

A subscription with a sustained high DLQ rate is auto-paused: MegatronLead stops sending new events to it until the subscription is acknowledged by an admin. This prevents a permanently-broken endpoint from generating endless retry traffic.

Operational concerns

Three patterns worth knowing:

Endpoint capacity. A high-volume subscription can produce many events per minute. Your endpoint should handle concurrent requests. If it cannot, you will queue at the gateway and eventually time out.

Long-running processing. If your endpoint's work takes more than a few seconds, respond 200 immediately and process asynchronously. A long-running HTTP handler increases timeout risk.

Filtering at subscription, not at endpoint. Subscribing to all events and filtering at your endpoint wastes traffic. Filter at subscription time so MegatronLead only sends what you need.

Audit trail

Every webhook delivery is recorded in the audit log: subscription ID, delivery ID, event type, target URL, response status, retry count. This serves two purposes:

• Operational debugging: when a webhook misfires, the audit trail shows what happened.
• Compliance evidence: when integrations carry compliance-relevant data, the audit log proves delivery.

The audit log retention applies to webhook delivery records the same as to other audit events.

For broader information on programmatic surfaces, see integrations and the platform overview.