v1

latestOpenAPI 3.1.02026-07-2498134321.1 KB

Webhooks

Create a Webhook

Creates a webhook for the specified events. Send separate requests if you need to create webhooks for multiple target URLs. Each target URL may only have one active registration.

OAuth Scope required: public.webhooks.createWebhooks

post/webhooks

Headers

x-as-user-emailstring

Example:jane.doe@test.com

Denotes the actor of the request. When used, the API will take into account this user's permissions and access. This or x-as-user-id is required when the associated token was produced from the Client Credentials grant or with legacy bearer tokens on select endpoints. More information about permissions.

x-as-user-idstring

Example:5f0375c4cdc1927a3c5edcd3

Denotes the actor of the request. When used, the API will take into account this user's permissions and access. This or x-as-user-email is required when the associated token was produced from the Client Credentials grant or with legacy bearer tokens on select endpoints. More information about permissions.

Request body

eventsWebhookEvent[] required

The event type(s) to trigger the webhook. Note: you can use * to receive events for all events, although we don't recommend this path, especially for environments with higher volume.

targetURLstring https-url required

The URL to send the webhook event payload to. It must be an HTTPS url.

status'enabled' | 'disabled'

The status of the webhook. If the status is disabled, the webhook will not be triggered.

Example request

{
  "events": [
    "workflow_launched"
  ]
}

Response

201

idstring required

Unique ID of the webhook

eventsWebhookEvent[] required

Array of events to which webhook is subscribed to.

targetURLstring https-url required

Target URL to which the webhook is called.

companyIdstring required

Unique ID of the Ironclad company instance to which the webhook belongs to.

status'enabled' | 'disabled' | 'disabledBySystem' required

The status of the webhook. If the status is disabled, the webhook will not be triggered.

statusLastUpdatedAtstring date-time

The timestamp of the most recent status change in ISO 8601 format.

statusLastUpdatedBystring

The user or system ID that made the most recent status change.

consecutiveFailureCountnumber required

The number of consecutive failed deliveries of the webhook. After a certain number of consecutive failures over a certain period of time, the webhook will be disabled. See more.

firstConsecutiveFailurestring date-time

The timestamp of the first consecutive failure of the webhook in ISO 8601 format.

Example response

{
  "id": "5928719b30182d3700364a74",
  "events": [
    "workflow_launched"
  ],
  "targetURL": "https://develop.ironcladapp.com",
  "companyId": "5928719b30182d3700364a74",
  "status": "enabled",
  "statusLastUpdatedAt": "2025-01-17T17:51:49.008Z",
  "statusLastUpdatedBy": "system",
  "firstConsecutiveFailure": "2025-01-17T17:51:49.008Z"
}