Create a webhook endpoint

​

Register an HTTPS endpoint. The response includes the signing secret (whsec_…) once — store it; later reads return only signing.secret_hint. Omitted settings take their defaults: audit.completed, every question set, all results, the standard payload fields, no receiver authentication. At most 20 endpoints per org (ENDPOINT_LIMIT_REACHED).

OAuth scopes
  • webhooks:write

Body·

required
application/json
  • url
    Type: string
    required

    HTTPS URL of your receiver (at most 2048 characters). The host must be a public DNS name: IP literals, single-label and local names, and hosts that resolve to private addresses are rejected with INVALID_WEBHOOK_URL.

  • authentication

    Receiver authentication. header sends a custom header; basic sends HTTP Basic; oauth2_client_credentials fetches a token (client_secret_post) and sends it as a Bearer token.

    Receiver authentication. header sends a custom header; basic sends HTTP Basic; oauth2_client_credentials fetches a token (client_secret_post) and sends it as a Bearer token.

    • type
      enum
      const:  
      none
      required
  • description
    Type: string | null

    Free-text label (at most 500 characters).

  • event_types
    Type: array of "audit.completed"enum
    const:  
    audit.completed

    Events to send. Default ["audit.completed"].

  • filters
    Type: object
    Properties: 2
  • payload
    Type: object
    Properties: 4
  • signing
    Type: object
    Properties: 1

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v2/webhook_endpoints
curl https://api.brellium.dev/v2/webhook_endpoints \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "url": "https://hooks.example.com/brellium",
  "description": "Production EHR sync",
  "event_types": [
    "audit.completed"
  ],
  "filters": {
    "question_set_ids": [
      ""
    ],
    "audit_results": "all"
  },
  "payload": {
    "fields": [
      "data.documentId"
    ],
    "result_format": "normalized",
    "responses_filter": "all",
    "include_informational_questions": true
  },
  "authentication": {
    "type": "none"
  },
  "signing": {
    "legacy_signature": true
  }
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "webhook_endpoint",
  "org_id": "string",
  "url": "https://hooks.example.com/brellium",
  "description": "Production EHR sync",
  "status": "enabled",
  "disabled_reason": "manual",
  "disabled_at": null,
  "event_types": [
    "audit.completed"
  ],
  "filters": {
    "question_set_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "audit_results": "all"
  },
  "payload": {
    "format": "standard_v1",
    "fields": [
      "data.documentId",
      "data.result",
      "responses",
      "responses.query",
      "responses.answer",
      "responses.context"
    ],
    "result_format": "normalized",
    "responses_filter": "all",
    "include_informational_questions": false
  },
  "authentication": {
    "type": "none"
  },
  "signing": {
    "secret_hint": "a1B2",
    "legacy_signature": false,
    "previous_secret_expires_at": null
  },
  "failing_since": null,
  "created_at": "2026-09-24T02:34:54.489Z",
  "updated_at": "2026-09-24T02:34:54.489Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwMfKQ9r8GKYo="
}

The created endpoint, with its signing secret

Previous
List webhook endpoints
Next
Get a webhook endpoint
Brellium API