Skip to content

B2B Lead Delivery: Webhook Integration Patterns

Build an application-owned webhook relay after a supported lead retrieval.

Dievio Team · Growth Systems · July 6, 2026 · 5 min read

A retrieved record passes through Client Code, then travels as an envelope to Your Webhook above the headline Fetch Then Forward.

Key points

  • Persist a supported retrieval before creating your own delivery event.
  • Separate receiver acceptance from completed CRM processing.
  • Retry delivery from stored results instead of repeating paid retrieval.

A webhook relay can move retrieved lead records into a CRM or internal workflow. The source lookup, the delivery event and the destination write are separate operations, with separate failure and billing rules.

This guide designs a relay owned by your application. Dievio's documented lead-search API provides request-and-response retrieval; the design below does not assume a native subscription to new leads, job changes or continuously verified contacts.

Put the relay after a supported source operation

  1. Retrieve a bounded batch. Use the documented endpoint, filters and numeric pagination.
  2. Persist the successful response. Record the operation, returned data and checkpoint before starting downstream work.
  3. Create your delivery event. Give it a stable event ID and an explicit schema version.
  4. Deliver to an approved receiver. Authenticate the message, handle duplicates and record the outcome.

If the main problem is destination field mapping, start with the lead-to-CRM sync workflow. A relay should not hide unresolved identity or overwrite rules.

Define an event contract you control

Choose the information the receiver needs instead of forwarding every available field. The following is an illustrative application event, not a Dievio payload or provider-defined event type.

{
  "event_id": "application-assigned-stable-id",
  "event_type": "lead_batch.ready",
  "schema_version": 1,
  "job_reference": "your-persisted-retrieval-operation",
  "batch_reference": "your-stored-result-reference"
}

Your receiver might fetch approved records from protected storage using the batch reference. If records travel in the message, minimize the payload and apply the same access and retention rules as the source data.

  • Keep one event ID across delivery attempts for the same logical event.
  • Record the supported source operation and relevant checkpoint separately from the delivery attempt number.
  • Define required fields, optional fields and version changes before connecting another client.
  • Use identifiers whose meaning your integration can support; do not invent a provider record ID that the response does not contain.

Make acceptance durable before acknowledging it

Specify what a successful receiver response means. A receiver can acknowledge after safely recording the event, then perform slower CRM writes in a worker. The acknowledgement and the eventual business result remain different states.

Separate delivery state from business state
StateWhat it establishesWhat remains to check
RetrievedThe source operation returned a response that your application storedRecord fit, field availability and approved use
Accepted by receiverThe receiver has durably recorded the delivery under the agreed contractDownstream validation and processing
Applied to destinationThe intended write or routing action completedConflicts, exceptions and activation eligibility
Needs reviewProcessing cannot safely continue automaticallyNamed owner, evidence and recovery decision

Persist receiver-side deduplication with the business action where your storage supports it. Otherwise, document the failure window and reconcile it. A repeated event must not silently create another contact or enrol the same person twice.

Dievio

Your workflow. Powered by Dievio.

Bring B2B contact search and LinkedIn enrichment into the tools you already use.

Explore Dievio API

Search contacts · Enrich profiles · Export results

Dievio APIExample
POST /api/public/search{ "job_titles": ["Founder"], "max_results": 10 }
Contacts ready for your workflow

Choose retries from the actual failure

A network timeout leaves uncertainty about what the receiver accepted. Keep the original event ID and inspect receiver state or use its duplicate-handling contract before repeating an action with consequences.

FailureInvestigateRecovery approach
Authentication or signature rejectionApproved secret, message construction and receiver configurationFix configuration before resending
Schema or required-field rejectionPayload version and validation detailCorrect the stored event or route it for review
Temporary capacity responseReceiver guidance and any documented retry delayUse bounded backoff and retain a retry limit
Connection failure or timeoutWhether the receiver already recorded the eventRetry the same logical event under the duplicate-handling policy

When the receiver supplies Retry-After, interpret its documented HTTP-date or delay value rather than assuming every retry can start immediately. The HTTP semantics specification defines that field.

Protect the receiver and its data

Use HTTPS, authenticate each request, validate the payload and restrict destination URLs to approved receivers. Keep source API keys and delivery secrets on the server; a receiving client should not need your source credential.

If you design message signatures, specify the exact signed bytes, secret rotation and replay handling. A plain source-IP check is not a complete authentication scheme. The OWASP REST security guidance covers transport, access controls and input validation.

Monitor the job through its final outcome

  • Trace the operation: connect retrieval reference, event ID, delivery attempts and destination result.
  • Measure delay: distinguish time waiting for delivery from time waiting for review or a destination write.
  • Track exceptions: separate rejected schemas, authentication failures, duplicates and unresolved identity conflicts.
  • Reconcile: compare accepted events with intended destination actions and investigate missing results.
  • Limit logs: keep diagnostic references and error categories without copying unnecessary contact data or secrets.

For agencies, keep client configuration, destination credentials and approval rules separate. A successful technical delivery does not establish permission to resell data or activate a contact.

Test the relay before connecting live retrieval

Begin with local fixtures for missing fields, duplicate events, delayed acknowledgements and receiver failures. Then test the documented source operation with a deliberately small live request and a controlled destination. See the API testing and fixtures guide for the distinction between mock tests and paid retrieval.

Use the Dievio API documentation to confirm the current source contract. Build the relay around persisted, reviewed results so delivery failures can be recovered without turning into another search.

Keep reading

Build your first list.

100 free credits. No credit card required.

Start free