> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Webhook

> Call an external HTTP endpoint during a flow and optionally save values from the response into variables.

## Description

The **Webhook | Response** tool calls an external HTTP endpoint and, optionally, writes selected values from the response into variables.

Good fits:

* Send call data to another system
* Look up a contact, claim, booking, or account in an external service
* Trigger an automation in Zapier, Make, n8n, a CRM, or an internal API
* Store selected fields from the webhook response into variables

***

## Manual Inputs

| Name         | Data Type | Required | Description                                       |
| ------------ | --------- | -------- | ------------------------------------------------- |
| URL          | string    | Yes      | Full endpoint to call, including `https://`       |
| Method       | string    | No       | HTTP method. Defaults to `POST` if left blank     |
| Headers      | json      | No       | Request headers, as valid JSON                    |
| Body         | string    | No       | Request body sent with `POST`, `PUT`, and `PATCH` |
| Response Map | object    | No       | Which response values to write into variables     |

### URL

The endpoint the tool should call. Use the full URL, including `https://`:

```text theme={null}
https://example.com/webhooks/inbound-call
```

You can include variables where the tool input supports variable substitution before execution.

### Method

The HTTP method to use. If you leave this blank, the tool uses `POST`.

| Method   | Use                                                |
| -------- | -------------------------------------------------- |
| `GET`    | Read data from an endpoint                         |
| `POST`   | Send data or trigger an action (the usual default) |
| `PUT`    | Replace or update a resource                       |
| `PATCH`  | Partially update a resource                        |
| `DELETE` | Delete or cancel a resource                        |

Use `POST` unless the external API specifically requires something else.

### Headers

Optional request headers — authentication tokens, API keys, content types, or vendor-specific headers. Common examples:

* `Authorization: Bearer <token>`
* `x-api-key: <key>`
* `Content-Type: application/json`

Headers must be valid JSON when configured as raw text. If the header JSON is invalid, the tool falls back to default headers and continues.

### Body

Optional request body. Use it to send information to the webhook, such as caller details, call results, or variables captured earlier in the flow.

* For `POST`, `PUT`, and `PATCH`, the body is sent with the request.
* For `GET`, the body is ignored — put lookup values in the URL or use the API's query-string format.

If the body is valid JSON, the tool sends it as JSON. Otherwise it is sent as raw text. Keep the body small and explicit — send only the fields the external system needs.

### Response Map

Optional. Tells the tool which values from the response should be written into variables. Use it when the webhook returns useful JSON, such as an ID, status, or URL.

The left side is the destination variable. The right side is the path inside the JSON response.

For this response:

```text theme={null}
data.customer.id = C-123
data.customer.email = jane@example.com
status = accepted
```

A matching response map:

```text theme={null}
{{custom.customer_id}}  -> data.customer.id
{{contact.email}}       -> data.customer.email
{{custom.webhook_status}} -> status
```

* Use dot notation to walk nested objects.
* Use number indexes for arrays — `results.0.name` is the `name` field on the first item in `results`.
* Use a blank response path to write the full JSON response into one variable.
* If the response is not JSON, the webhook can still succeed, but Response Map cannot write values.
* If a response path is missing, that one write is skipped. The tool still succeeds if the request returned a 2xx response.

***

## Manual Outputs

| Name   | Data Type | Description                                          |
| ------ | --------- | ---------------------------------------------------- |
| result | bool      | `true` if the endpoint returned an HTTP 2xx response |

***

## Conditions

### Success (true)

The endpoint returned an HTTP 2xx response.

### Failure (false)

The URL was missing, the method was invalid, the request failed or timed out, or the endpoint returned a non-2xx status.

***

## Example Usage

Trigger a simple webhook:

```text theme={null}
URL: https://hooks.example.com/call-complete
Method: POST
Headers: Authorization and Content-Type headers
Body: Call summary and captured variables
Response Map: blank
```

Look up a customer and save the returned ID:

```text theme={null}
URL: https://api.example.com/customer/search
Method: POST
Headers: API key or bearer token
Body: Phone number or email from the current contact
Response Map:
  {{custom.customer_id}} -> data.customer.id
```

Save a booking URL from a response:

```text theme={null}
URL: https://api.example.com/bookings
Method: POST
Body: Customer name, email, and requested appointment time
Response Map:
  {{custom.booking_url}}    -> data.booking.url
  {{custom.booking_status}} -> data.booking.status
```

***

## Common Issues

* **Returns `false`** — check the endpoint status code, URL, method, and authentication headers.
* **Service says the body is invalid** — validate the body JSON and confirm the API's expected field names.
* **Response values are not written** — check that the response is JSON and the Response Map paths match the actual response.
* **One mapped value is missing** — that path probably does not exist in the response.
* **A `GET` is not sending body data** — move those values into the URL query string, or use the method the API expects.
* **Authentication fails** — confirm whether the service expects a bearer token, API key header, basic auth, or a token in the URL.

***

## Best Practices

1. **Use `POST`** for generic webhook triggers
2. **Map only what you need** — use Response Map for fields the flow uses later
3. **Store stable values** — identifiers, statuses, and URLs rather than entire large responses
4. **Test response paths** — keep them short and verify against a real sample response
5. **Avoid hard-coded secrets** — prefer a safer secret or integration mechanism over secrets in script text

***

## Next Steps

* [Code Step](/tools/code-step/overview) — Parse and route on a webhook response with `json_loads`
* [Tool Steps](/flows/steps-tool) — Learn how to configure tool steps
* [Variables](/flows/variables) — See all available variables