IRironcladapp
Webhooks

Create a Webhook

Changed on

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

Request

  • Base URL
    https://ironcladapp.com/public/api/v1
  • URL
    https://ironcladapp.com/public/api/v1/webhooks
  • Auth
    API key in header Authorization and OAuth 2
    Authorization code: https://ironcladapp.com/oauth/authorize
    Client credentials
    Token URL: https://ironcladapp.com/oauth/token scopes: public.webhooks.createWebhooks

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. A token produced from the Authorization Code grant (which is already scoped to a user) may also use this header to act as a different user in the same company, provided the token carries the identity.users.impersonate scope and the token's own user has been granted the API User Impersonation permission. A request that sends this header without both never acts as the named user; depending on the company's configuration it either proceeds as the token's own user or is rejected with a 403. 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. A token produced from the Authorization Code grant (which is already scoped to a user) may also use this header to act as a different user in the same company, provided the token carries the identity.users.impersonate scope and the token's own user has been granted the API User Impersonation permission. A request that sends this header without both never acts as the named user; depending on the company's configuration it either proceeds as the token's own user or is rejected with a 403. 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"
}

Changes

  • 435da5a4396eRevision changes
    • warning

      added the new workflow_deleted enum value to the / response property for the response status

    • info

      added the new workflow_deleted enum value to the request property /