Configuring webhooks

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.

Register an endpoint

POST /partner/v1/webhook-config

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.

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

string

required

The HTTPS URL TruEnroll will POST events to. Must be reachable from the public internet.

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.

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.

string

An optional human-readable label for the endpoint, useful when you register more than one.

Response

{
  "success": true,
  "message": "webhook config created successfully",
  "meta": {},
  "data": {
    "id": "6850abc123def456ghi789"
  }
}

string

The unique ID of the registered webhook configuration.

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 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

curl https://api.truenroll.com/partner/v1/webhook-config \
  -H "x-api-key: $TRUENROLL_API_KEY"

{
  "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).

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

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

Webhook events

Every event name, payload, delivery behavior, and how to verify incoming requests.

Overview

Guides

API Reference

Configuring webhooks

Register an endpoint

Request fields

Response

How the secret is used

Managing endpoints

List endpoints

Update or rotate the secret

Delete an endpoint

Notes

Errors

Webhook events

​Register an endpoint

​Request fields

​Response

​How the secret is used

​Managing endpoints

​List endpoints

​Update or rotate the secret

​Delete an endpoint

​Notes

​Errors

Webhook events

Register an endpoint

Request fields

Response

How the secret is used

Managing endpoints

List endpoints

Update or rotate the secret

Delete an endpoint

Notes

Errors