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
- Retrieve a bounded batch. Use the documented endpoint, filters and numeric pagination.
- Persist the successful response. Record the operation, returned data and checkpoint before starting downstream work.
- Create your delivery event. Give it a stable event ID and an explicit schema version.
- 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.
| State | What it establishes | What remains to check |
|---|---|---|
| Retrieved | The source operation returned a response that your application stored | Record fit, field availability and approved use |
| Accepted by receiver | The receiver has durably recorded the delivery under the agreed contract | Downstream validation and processing |
| Applied to destination | The intended write or routing action completed | Conflicts, exceptions and activation eligibility |
| Needs review | Processing cannot safely continue automatically | Named 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.
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.
| Failure | Investigate | Recovery approach |
|---|---|---|
| Authentication or signature rejection | Approved secret, message construction and receiver configuration | Fix configuration before resending |
| Schema or required-field rejection | Payload version and validation detail | Correct the stored event or route it for review |
| Temporary capacity response | Receiver guidance and any documented retry delay | Use bounded backoff and retain a retry limit |
| Connection failure or timeout | Whether the receiver already recorded the event | Retry 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.



