01 · Direct answer
How do you use webhooks for direct mail automation?
The source system sends one documented event. The receiving workflow validates the payload, checks the address and duplicate key, renders a proof, and records a release decision. A webhook is only the transport. The controls around it determine whether the workflow is safe.
Use direct mail automation for the broader operator workflow and direct mail API guidance for record design.
- Choose the eventName the exact business change that makes the record eligible.
- Define the payloadSend stable IDs, structured address fields, template data, and test state.
- Define the resultReturn and store accepted, held, failed, and released states.
02 · Direct answer
How do you send one personalized postcard from a webhook?
Map each source field to one named template field. Keep recipient name and postal address separate from optional personalization, such as property city, service type, or order number. Use a fallback or hold the record when an optional value is empty.
Render a proof from the same payload that will create the mail record. Save the template version with the source event ID.
03 · Direct answer
How do you map CRM fields to postcard personalization fields?
For example, map contact.firstname to first_name, property.city to property_city, and the CRM record ID to source_record_id. Do not place the same field in the address block and the marketing copy unless both uses are intentional.
A visible field map makes changes reviewable. It also stops a CRM rename from silently creating blank postcard copy.
04 · Direct answer
How do you test a direct-mail webhook without sending live mail?
Send a test flag or use the account's approved test environment. Confirm that the request authenticates, validates, deduplicates, renders, and returns a test result. A successful HTTP response alone does not prove that the proof or field map is correct.
If no non-mailing test mode is available, stop. Do not use a real address as a substitute for an explicit test boundary.
05 · Direct answer
How do you handle webhook retries without sending duplicate postcards?
Reuse the same event ID and idempotency key. Store the first accepted result. If the same key returns with the same payload, return the saved result. If the payload changes, hold the request for review.
Use the detailed direct-mail idempotency key guide to define key scope and retention.
06 · Direct answer
How do you use an idempotency key for a physical-mail request?
A useful key can combine the source system, source record ID, trigger name, and allowed send window. Do not generate a new random key for every retry. That defeats duplicate protection.
Keep the key after the network request finishes. Physical production cannot always be reversed after release.
07 · Direct answer
How do you pause a direct-mail automation without deleting the connection?
A paused workflow can continue to record or hold eligible events, but it must not release mail. Show the pause owner, start time, reason, held-record count, and restart decision. Do not rely only on deleting a webhook URL.
Decide whether held events expire, need manual review, or can release after restart.
08 · Direct answer
How do you handle a missing or invalid mailing address in an automated workflow?
Separate missing fields, malformed fields, secondary-unit risk, and other address exceptions. Write the reason to the source system when possible. Do not guess a unit number or silently drop part of an address.
Use the mailable address guide for the review fields that support this decision.
09 · Direct answer
How do you track a webhook-triggered postcard after submission?
Subscribe to available status events and save each event with its time and source. Mailstream visibility can support operations. It does not prove that a person saw the piece, responded, or caused revenue.
Use the USPS postcard tracking guide for measurement boundaries.
10 · Direct answer
How do you write mail status back to a CRM?
Store the source event ID, current operational state, exception reason, campaign ID, mailpiece ID, and event time. Keep trigger fields separate from result fields so the writeback cannot replay the send workflow. Use a related record when one contact, deal, or property can have several mail events.
Label accepted, held, failed, released, mailstream, response, and revenue states separately. One state does not prove another.
Implementation worksheet
Webhook contract worksheet
Define these fields before anyone writes the first production request.
| Control | Example value | Decision before launch |
|---|---|---|
| Source event | lead.created, job.closed, or payment_intent.succeeded | Use the event that proves the business condition. Do not use a nearby event. |
| Source key | CRM record ID or order ID | Keep one stable key through retries and writeback. |
| Recipient | Name plus structured postal fields | Hold incomplete or ambiguous records for review. |
| Creative | Template ID, version, and merge fields | Render the exact values that the recipient will see. |
| Duplicate rule | Source key plus send window | Choose when a repeat event can create another piece. |
| Result | Accepted, held, failed, or released | Write a clear status and reason back to the source system. |
Preflight checklist
- Use one stable source-event ID and save it with the mail record.
- Require recipient name, address line 1, city, state, and ZIP Code before release.
- Set a duplicate rule for the person, household, property, order, or job.
- Render a proof with a test record before any funded send.
- Define who can pause the workflow and who can approve release.
- Store the source record ID, campaign ID, and returned mailpiece ID together.
- Treat mailstream events as operational signals, not proof of attention or revenue.
FAQ
Questions to resolve before launch
Does a 200 response mean the postcard was mailed?
No. It can mean only that the receiver accepted the request. Store the returned state and do not call the piece mailed until the workflow reports a release state.
Can a webhook retry create duplicate mail?
Yes. A retry can create another mail record if the receiver does not enforce idempotency and duplicate rules.
Does tracking prove delivery or response?
No. Mailstream events are operational signals. They do not prove recipient exposure, response, or revenue.
Primary sources
Sources and review notes
- GitHub Docs: About webhooksOfficial overview of webhook event delivery and payloads.
- Shopify Flow: Send HTTP requestOfficial retry and HTTP-request behavior for an established event source.
- Stripe: WebhooksOfficial guidance for event IDs, retries, signatures, and duplicate events.
Product plans, trigger names, and connector access can change. Check the linked documentation and your account before production use. Sendvo last reviewed these sources on August 31, 2026.