---
title: "Create a new webhook"
method: POST
path: "/webhooks"
tags: ["Webhook"]
---

# Create a new webhook

`POST /webhooks`

Creates a new webhook subscription with the provided details. The webhook will receive events asynchronously when the specified event types occur.


**Available Event Types:**

- `credential_workflow.status.changed` - Triggered automatically when a credentialing workflow status changes (timeline event is created). See webhook-api-credential-workflow-events.md for detailed payload structure and documentation.

- `facility_credential_workflow.status.changed` - Triggered automatically when a facility credentialing workflow status changes (timeline event is created).


You can subscribe to multiple different event types in a single webhook.

## Headers

- `tenant-id` string, required

## Request body

- WebhookRequest — Request to create a new webhook
  - `webhookUrl` string, required — The URL where webhook events will be sent
  - `eventTypes` WebhookEventType[], required — List of event types that this webhook should receive. You can subscribe to multiple different event types in a single webhook. **Available Event Types:** - `credential_workflow.status.changed` - Triggered automatically when a credentialing workflow status changes (timeline event is created). See webhook-api-credential-workflow-events.md for detailed payload structure and documentation. - `facility_credential_workflow.status.changed` - Triggered automatically when a facility credentialing workflow status changes.
  - `headers` object — Custom headers to include in webhook requests
  - `isActive` boolean — Whether the webhook is active. Defaults to true if not provided
  - `oauthConfiguration` WebhookOauthConfiguration — OAuth client-credentials configuration. When present, a token is fetched before each delivery and injected as Authorization: Bearer <token>.
    - `tokenUrl` string, required — OAuth token endpoint URL
    - `clientId` string, required — OAuth client ID
    - `clientSecret` string, required — OAuth client secret
    - `scope` string — OAuth scope(s) to request, space-separated
    - `headers` object — Additional headers to send with the token request
    - `resource` string — Resource to request

## Response `201`

Successfully created the webhook

- WebhookResponse — Response containing a single webhook
  - `id` string — Unique identifier for the webhook
  - `tenantId` string — ID of the tenant
  - `data` WebhookDataSchema — Schema for webhook data payload
    - `webhookUrl` string, uri, required — The URL endpoint where webhook events will be sent
    - `eventTypes` string[], required — List of event types that will trigger this webhook
    - `headers` object, nullable — Custom HTTP headers to include in webhook requests
    - `isActive` boolean, required — Whether the webhook is currently active and will receive events
  - `createdBy` string — ID of the user who created the webhook
  - `updatedBy` string — ID of the user who updated the webhook
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400` — Invalid request data. Returns validation errors for deserialization failures (e.g., invalid enum values) or constraint violations (e.g., empty eventTypes, mixed event types, invalid URL format).
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - User does not have required permissions
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/3d27e9019c7b/schema)