Back to API overview
Webhooks
5 endpoints
Receive real-time events from WordAuth for integration and automation.
webhooks.read
webhooks.manage
Register HTTPS webhook endpoints for OS events. Delivery is recorded; outbound dispatch is best-effort.
Authenticate with your organization API key. Include
subOrgId as a query parameter or in the request body when using an org-wide key. Sub-org-scoped keys automatically target their sub-organization.GET
/v1/webhooksList webhook endpoints. Requires webhooks.read.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| subOrgId | string | No | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Response — 200
{ "webhooks": [ /* endpoints */ ] }
POST
/v1/webhooksCreate a webhook endpoint. Returns a signing secret once. Requires webhooks.manage.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| subOrgId | string | No | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Request Body
| Param | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Webhook display name |
| url | string | Yes | HTTPS endpoint URL |
| events | string[] | Yes | Event types to subscribe to |
| subOrgId | string | Yes | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Response — 200
{ "webhook": { /* ... */ }, "signingSecret": "whsec_..." }
GET
/v1/webhooks/{webhookId}Get a webhook; optionally include recent deliveries. Requires webhooks.read.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| subOrgId | string | No | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
| deliveries | boolean | No | Include recent delivery attempts when true |
| limit | integer | No | Max events to return (default 50, max 200; CSV export max 1000) |
Response — 200
{ "webhook": { /* ... */ }, "deliveries": [] }
PATCH
/v1/webhooks/{webhookId}Update webhook URL, events, or enabled state. Requires webhooks.manage.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| subOrgId | string | No | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Request Body
| Param | Type | Required | Description |
|---|---|---|---|
| name | string | No | Webhook display name |
| url | string | No | HTTPS endpoint URL |
| enabled | boolean | No | Whether the webhook is active |
| events | string[] | No | Event types to subscribe to |
| subOrgId | string | Yes | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Response — 200
{ "webhook": { /* updated */ } }
DELETE
/v1/webhooks/{webhookId}Delete a webhook endpoint. Requires webhooks.manage.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| subOrgId | string | No | Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org. |
Response — 200
{ "success": true }