Receiving Webhooks from Voxworks

​

Overview

A Voxworks automation can end its pipeline with a Destination step of kind Webhook, which sends an HTTP request to a URL you control whenever the automation runs — for example, posting a call summary to your own backend after every completed call. This page is for the developer building the endpoint that receives those requests: what the request looks like, how to tell deliveries apart, what happens when your endpoint is slow or down, and what your URL needs to satisfy before Voxworks will send to it.

---

​

Setting up a webhook destination

In an automation’s pipeline builder, a Destination step configured with kind Webhook exposes: {{path}} placeholders resolve against the automation’s pipeline context — trigger, call, contact, custom, source, mapped, results, automation_id, execution_id, and created_by — the same context used throughout the pipeline. See Field Mapping & Context for the full reference of what’s available at each field. If you leave Body Template blank, Voxworks sends the request with no body at all — there’s no automatic default payload built from the trigger data. If you want the trigger or call data in the request, put it in the Body Template explicitly.

---

​

Request shape

• Method and URL — exactly as configured on the step, after {{path}} interpolation.
• Content-Type — set to application/json automatically whenever a JSON body is sent. If Body Template is empty, no body and no Content-Type header are sent.
• Headers — your configured headers, plus one header Voxworks always adds: X-Execution-Id.
• Timeout — Voxworks waits up to 30 seconds for your endpoint to respond. This isn’t configurable per step.

​

The X-Execution-Id header

---

​

Retries, backoff, and the duplicate-delivery caveat

Retries apply to the automation execution as a whole, not to the webhook delivery in isolation. An automation’s pipeline runs top to bottom; if any step other than a Destination step raises an error, the whole execution is scheduled to run again later. Destination steps (including webhook deliveries) are treated as independent — if a webhook delivery itself fails (connection error, timeout, or a blocked URL), that step is recorded as failed and the pipeline continues to the next step, but that failure alone does not schedule a retry. This has an important consequence: if a webhook Destination step succeeds, but a later step in the same pipeline (an Upsert Contact, an Upsert Custom Variable, a Create Call, and so on) fails, the entire execution is retried from the beginning — including the webhook step that already succeeded. Your endpoint will receive the same request again, with the same X-Execution-Id, even though the first delivery went through fine. When a retry is scheduled, the delay before the next attempt grows with each failure: An execution gets up to 5 attempts. If it’s still failing after the 5th, it’s marked Dead Letter and stops retrying. Two more behaviours worth knowing when you’re designing around this:

• Non-2xx responses from your endpoint aren’t treated as failures. Voxworks records whatever status code and body your endpoint returns, but it doesn’t inspect the status code to decide whether to retry — only a network-level failure (connection error, DNS failure, timeout) on a non-Destination step schedules a retry. Returning 500 from your webhook endpoint will not, by itself, cause Voxworks to resend that delivery.
• A blocked or unreachable webhook URL doesn’t stop the rest of the pipeline. If your URL fails validation or the request errors, the Destination step is marked failed in the Execution Log and the automation continues to any steps after it.

---

​

URL and network requirements

Every webhook URL — checked fresh on every attempt, after {{path}} interpolation — must satisfy:

• Scheme — http or https only.
• A resolvable hostname. URLs whose hostname can’t be resolved are rejected outright.
• No private, loopback, or link-local addresses. Voxworks blocks requests to:
  • 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (private ranges)
  • 127.0.0.0/8 (loopback)
  • 169.254.0.0/16 (link-local — this also covers common cloud metadata endpoints)
  • 0.0.0.0/8
  • ::1/128 and fd00::/8 (IPv6 loopback and unique local addresses)
  • the hostnames metadata.google.internal and metadata.google.com explicitly

In practice: your webhook URL needs to be a publicly routable http/https address. Internal, localhost, or cloud-metadata URLs are rejected before any request is sent. There’s currently no request-signing header (no HMAC) on outbound webhook deliveries — X-Execution-Id is the only Voxworks-added header. If you need to confirm a request genuinely came from Voxworks, treat the URL itself (a long, unguessable path) as the shared secret rather than expecting a signature to verify.

---

​

Response logging

Every automation run appears in the automation’s Execution Log (Automations > select an automation > Execution Log). Expanding a run shows each pipeline step and its result — for a webhook Destination step, that includes the status code and response body Voxworks received back from your endpoint. Response bodies are captured for logging up to 10KB; anything your endpoint returns beyond that is truncated. See Execution Log & Monitoring for the full breakdown of statuses and what’s stored per run.

---

​

Recommended endpoint patterns

• Dedupe on X-Execution-Id. Store recently seen IDs and skip processing a request you’ve already handled — this is the only reliable way to make repeat deliveries safe, given the duplicate-delivery caveat above.
• Respond quickly. Voxworks waits up to 30 seconds; if your processing is slow, acknowledge the request immediately with a 2xx and do the real work asynchronously rather than making Voxworks wait on it.
• Validate the payload defensively. The body shape is whatever your team configured in Body Template — treat it as untrusted input and check for the fields you expect before using them.
• Use HTTPS. http is accepted, but an endpoint on the public internet should be encrypted.
• Don’t rely on your response code to trigger a resend. As covered above, returning an error doesn’t make Voxworks retry that delivery — if you need guaranteed reprocessing, handle that on your own side (e.g. a dead-letter queue on your endpoint).

---

​

Next Steps