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

# Configuring webhooks

> Register an HTTPS endpoint to receive Partner API events.

Before TruEnroll can deliver events, you register the HTTPS endpoint that should receive them.
You can do this yourself through the Partner API. Once an endpoint is registered, TruEnroll
posts an event to it each time a processing stage completes or fails.

For the shape of the events you'll receive and how to handle them, see
[Webhooks](/partner-api/webhooks).

## Register an endpoint

```
POST /partner/v1/webhook-config
```

<Note>
  This endpoint is also available at `/v1/webhook-config`. Both paths accept the same request;
  use whichever fits your integration. The examples below use the Partner API path.
</Note>

```bash theme={null}
curl -X POST https://api.truenroll.com/partner/v1/webhook-config \
  -H "x-api-key: $TRUENROLL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://example.com/truenroll/webhook",
    "apiKey": "whsec_a1b2c3d4e5f6g7h8i9j0",
    "description": "Production case events"
  }'
```

### Request fields

<ParamField body="endpoint" type="string" required>
  The HTTPS URL TruEnroll will POST events to. Must be reachable from the public internet.
</ParamField>

<ParamField body="apiKey" type="string" required>
  A secret you choose, at least 20 characters. TruEnroll sends it back as the `x-api-key`
  header on every delivery, so your endpoint can confirm each request genuinely came from
  TruEnroll. Treat it like a password and store it in a secret manager.
</ParamField>

<ParamField body="audience" type="string" default="partner">
  On the Partner API this defaults to `partner`, so the endpoint receives case events. You
  normally don't need to set it.
</ParamField>

<ParamField body="description" type="string">
  An optional human-readable label for the endpoint, useful when you register more than one.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "message": "webhook config created successfully",
  "meta": {},
  "data": {
    "id": "6850abc123def456ghi789"
  }
}
```

<ResponseField name="data.id" type="string">
  The unique ID of the registered webhook configuration.
</ResponseField>

## How the secret is used

The `apiKey` you supply is a shared secret between you and TruEnroll. On every webhook
delivery, TruEnroll includes it as the `x-api-key` request header. Your endpoint should
compare that header against the value you registered and reject the request if it doesn't
match. See [Authenticating webhook requests](/partner-api/webhooks#authenticating-webhook-requests)
for the verification snippet.

## Managing endpoints

List, inspect, update, and remove your registered endpoints with the same `x-api-key` auth.
The shared `apiKey` secret is never returned in any response.

### List endpoints

```bash theme={null}
curl https://api.truenroll.com/partner/v1/webhook-config \
  -H "x-api-key: $TRUENROLL_API_KEY"
```

```json theme={null}
{
  "success": true,
  "message": "webhook configs retrieved",
  "meta": {},
  "data": [
    {
      "id": "6850abc123def456ghi789",
      "endpoint": "https://example.com/truenroll/webhook",
      "audience": "partner",
      "description": "Production case events",
      "createdAt": "2026-06-22T10:00:00.000Z",
      "updatedAt": "2026-06-22T10:00:00.000Z"
    }
  ]
}
```

Fetch a single endpoint with `GET /partner/v1/webhook-config/{id}`.

### Update or rotate the secret

Send only the fields you want to change. To rotate the shared secret, pass a new `apiKey`
(remember to update your endpoint's stored value at the same time).

```bash theme={null}
curl -X PATCH https://api.truenroll.com/partner/v1/webhook-config/6850abc123def456ghi789 \
  -H "x-api-key: $TRUENROLL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "whsec_rotated_secret_0987654321" }'
```

### Delete an endpoint

```bash theme={null}
curl -X DELETE https://api.truenroll.com/partner/v1/webhook-config/6850abc123def456ghi789 \
  -H "x-api-key: $TRUENROLL_API_KEY"
```

A deleted endpoint stops receiving events immediately and returns `204 No Content`. Its URL
becomes available to register again.

## Notes

* **HTTPS is required.** The header is sent on every request, so the endpoint must be served
  over TLS to keep the secret private.
* **One active URL per organization.** Each endpoint URL can be registered once. Registering a
  URL that is already active returns `409`.
* **Multiple endpoints are allowed.** Register different URLs (for example, separate staging and
  production endpoints) by calling the endpoint once per URL.

## Errors

| Code  | Reason                                                                                                          |
| ----- | --------------------------------------------------------------------------------------------------------------- |
| `400` | Invalid body: `endpoint` is not a valid URL, `apiKey` is shorter than 20 characters, or a `PATCH` had no fields |
| `401` | No API key, or an invalid/expired key                                                                           |
| `403` | Key is not a partner key, or the key is inactive                                                                |
| `404` | No webhook config with that ID (on `GET`, `PATCH`, `DELETE` by ID)                                              |
| `409` | An active endpoint with that URL already exists                                                                 |

<Card title="Webhook events" icon="bell" href="/partner-api/webhooks">
  Every event name, payload, delivery behavior, and how to verify incoming requests.
</Card>