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

# HTTP request definitions

> Define the HTTP request Roark fires to place outbound calls through your own system

An `httpRequestDefinition` is a reusable HTTP request Roark fires to hand off **outbound dialling** to your own system. An [agent endpoint](/documentation/config-as-code/agents#outbound-dialling) whose `outboundDialType` is `HTTP_REQUEST` references one by name, and Roark calls it (substituting the number to dial) when a call should be placed.

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json
kind: httpRequestDefinition
name: dialer
description: Places outbound calls through our telephony gateway
url: https://dialer.example.com/dial
method: POST
body: '{"to":"{{phoneNumberToDial}}"}'
headers:
  Authorization: 'Bearer YOUR_TOKEN'
```

| Field         | Default | Notes                                                                                                                    |
| :------------ | :------ | :----------------------------------------------------------------------------------------------------------------------- |
| `name`        | —       | The local key (`^[a-z0-9][a-z0-9-_.]*$`); what an endpoint's `outboundDialHttpRequestDefinition` references              |
| `url`         | —       | Where Roark sends the request. Public `http(s)` only: localhost, private, and link-local hosts are rejected              |
| `method`      | `POST`  | `POST`, `PUT`, `PATCH`, or `GET`                                                                                         |
| `body`        | `{}`    | Request body template. A string that may carry placeholders Roark substitutes at dial time, e.g. `{{phoneNumberToDial}}` |
| `headers`     | —       | Static request headers sent verbatim, for example an `Authorization` bearer token for your endpoint                      |
| `description` | —       |                                                                                                                          |

It reconciles **before** agents, so an endpoint that references it in the same bundle resolves in one apply. Reference it only from a config-managed definition (declared in the bundle or a previous apply).

## Signing secret

Roark mints an HMAC **signing secret** for each definition so your endpoint can verify a request genuinely came from Roark. It is **not** declared in your config: it is generated on create and returned exactly once, in the `apply` response's `signingSecret` for that resource.

<Warning>
  Capture the `signingSecret` from the apply response when the definition is first created: it cannot be read back afterwards. If you lose it, delete and re-apply the definition to mint a new one. Editing the other fields updates the definition in place and leaves the secret untouched.
</Warning>

## Ownership

Once a definition is managed by config, it is read-only in the dashboard and over the API: `PUT /v1/http-request-definition/{id}` returns `409`, and the response's `isConfigManaged` is `true`. Change it in your config and re-apply, or detach it first to release it back to dashboard ownership.

<Note>
  Only outbound-dial definitions are managed here. Webhook and alert-delivery HTTP requests own their own lifecycle and are configured elsewhere.
</Note>

<Note>
  For the full field reference of every kind, see the [Config DSL reference](https://roark.ai/roark-config.schema.json) schema.
</Note>