Attribution Webhooks: Prove Receipt, Processing and Reconciliation

An attribution webhook is not a complete reporting ledger. To trust it, prove three different things: your endpoint accepted an authentic event, your downstream system processed it correctly, and your resulting records reconcile with an authoritative source.

Each stage needs separate evidence. Original editorial illustration, not an Attribi dashboard.

A connection test can return success while the report remains unchanged. The receiver might accept the request and fail later. A spreadsheet write might succeed in the wrong workspace. An event might reach the endpoint but never enter a durable work queue.

These are different failures. Treating all of them as "the webhook is broken" makes diagnosis slower. This guide gives marketing operations teams and agencies a practical acceptance framework. The receiver design described here is a recommendation, not a claim that Attribi supplies a queue, warehouse or recovery service.

Give each stage its own evidence

Start with four states:

• Received: The endpoint observed the request.
• Accepted: The receiver validated it and durably recorded the work it intends to perform.
• Processed: The intended destination operation completed.
• Reconciled: The business result agrees with the chosen control source, or the difference has a documented explanation.

A received event is not necessarily authentic. An accepted event is not necessarily processed. A processed event is not necessarily the right business result. Adding a row to the wrong client's spreadsheet is a technically completed operation and a failed business outcome.

Use these states in your internal reporting instead of a single green connected label.

Understand the sender's contract before designing recovery

Attribi's webhook integration page describes outbound lead-created, qualified and closed-won events sent to one HTTPS endpoint. It documents HMAC-SHA256 signing, a five-second timeout and one delivery attempt, with no automatic retry or replay queue. A public attribution-query API is described as planned, not available.

The page also states that email is the field shared across the three event types; their visitor and lead identifiers differ. Do not assume one identifier appears everywhere.

These documented limits affect the receiver's design. A queue you build can protect an event after your system has durably accepted it. It cannot recover an event that never reached you. Confirm the current contract and inspect authorised test payloads before implementation. Do not build against imagined fields.

Design the fast path around durable acceptance

A useful proposed receiving sequence is:

1. Capture the request in the form needed for authentication.
2. Verify the sender using its documented method.
3. Check the event type and required fields.
4. Store the accepted event or enqueue its processing durably.
5. Return the appropriate acknowledgement.
6. Perform slower downstream work outside the request's critical path.
7. Record success or failure against the accepted event.

This separation keeps a slow spreadsheet, CRM or reporting service from unnecessarily delaying the inbound request.

Stripe's official webhook guidance illustrates the general pattern: asynchronous processing, signature verification using the unmodified request body and prompt successful responses before complex work. Those are design principles, not evidence that Stripe's delivery guarantees apply to Attribi. See Stripe webhook guidance.

Do not acknowledge success before the point your design defines as durable acceptance. Otherwise, a process crash can erase the event after the sender believes it was accepted. The exact transaction and queue design belongs with the engineer responsible for the receiver.

Proposed receiver architecture. The queue and worker are components your team would supply, not built-in Attribi services.

Keep the raw event separate from the business record

The event is evidence about something that happened. The reporting row is your interpretation of that evidence. Store enough information to investigate the transformation:

• When the receiver observed the event.
• Which workspace or client it belongs to.
• Event type and relevant source identifiers, when provided.
• Validation outcome.
• Processing status and attempt history.
• Destination record identifier.
• A structured explanation for rejection or failure.

Avoid unnecessarily copying personal information into general application logs. Decide access controls, retention and permitted uses before sending event data to another service. This is a data-handling design requirement, not a blanket claim of legal compliance.

For an agency, workspace separation should be explicit. Do not use an email address alone as a global key across unrelated clients. If email is the only shared identity in a particular contract, document its limitations: people change addresses, shared mailboxes exist, and a person is not the same unit as a deal.

Do not invent a universal deduplication key

Deduplication means preventing the same business effect from being applied twice. It does not mean discarding every event from someone you have seen before.

A rule such as "ignore an email after the first event" could suppress a later qualification or won outcome. A rule such as "ignore everything on the same day" could collapse legitimate separate events.

Inspect the sender's actual identifiers and semantics. Distinguish a repeated delivery of the same event, a new stage for the same person, a new transaction and a correction to a previous transaction.

If the payload lacks a dependable unique event identifier, document that limitation. Do not fabricate a guaranteed deduplication scheme from fields that do not uniquely represent the business event. Your receiving system may still use a carefully designed processing key, but it should be tested against the actual lifecycle and approved by its responsible engineer.

Test failure, not only the happy path

A single successful test proves little about operational reliability. Create an acceptance sheet with each test, expected result and observed evidence.

Normal event: One authentic event reaches the correct destination and creates the expected business result.

Invalid signature: The event is rejected and does not trigger a downstream business action.

Malformed required data: A documented validation policy applies, rather than silently creating a misleading report row.

Slow destination: The receiver's acceptance path remains independent of delayed downstream work.

Duplicate processing attempt: A retry within your own system does not create a second business effect.

Worker failure after acceptance: Accepted work remains discoverable and recoverable within your processing system.

Client-routing error: A test cannot cross into another client's data.

Missing inbound event: Reconciliation detects the gap rather than assuming silence means zero activity.

These are test requirements for a proposed receiver, not claims about built-in Attribi features.

A successful response is not a revenue total

Consider an illustrative daily review. The receiver accepted 20 events. The worker completed 19. One remains in a documented failure state. The 19 completed events include several funnel stages for the same people.

The report should not conclude that 20 customers converted or that 19 distinct sales occurred. Event counts, people counts and transaction counts are different units. Similarly, do not add every value-bearing update without understanding whether it represents a new amount, a replacement or a separate transaction.

For US and European reporting, preserve the currency attached to each value. Currency conversion for a management report should be a separate, documented transformation, not an assumption hidden inside event processing. All numbers in this example are illustrative only.

Reconcile against a source that answers the business question

Choose the control source before relying on the feed. If the downstream report claims to show closed commercial outcomes, determine which CRM, order system or approved export establishes that total. Define the period, status and currency consistently.

Then classify differences:

• Not received.
• Received but rejected.
• Accepted but not processed.
• Processed into the wrong destination.
• Matched to the wrong identity.
• Excluded under the agreed measurement definition.
• Still within an expected timing difference.

A recovery plan should say who investigates each category and how the correction is evidenced. Avoid silently editing reports to make totals match. If your requirement depends on retrieving every missed historical event, verify that an appropriate source and retrieval route actually exist. A planned public API is not a recovery mechanism you can use today.

For alternative documented destinations, review Attribi's integrations and assess the specific workflow rather than assuming every connection provides the same guarantees.

Trust a webhook workflow only when you can explain what happened between the inbound request and the final business record. Separate acceptance from processing, test failures deliberately, and keep an independent way to identify missing outcomes.

Frequently asked questions

Does a 2xx response prove the report updated?

No. It proves only the success condition implemented by that endpoint. Establish what the receiver durably stored before returning the response, then inspect downstream processing separately.

Should every webhook provider use the same retry assumptions?

No. Delivery, ordering, retention and replay behaviour are provider-specific. Read the current contract rather than copying another service's defaults.

Can I treat all funnel events as separate customers?

No. A person can generate multiple lifecycle events. Define whether each report counts events, people, opportunities or transactions.

What should an agency approve before launch?

The client and workspace boundary, payload contract, authentication, durable-acceptance point, processing rules, failure ownership and reconciliation source.