> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Register a webhook

`POST /api/web/v1/webhooks`

Register a webhook with callback URL, webhook events etc. Caller is required to have WEBHOOKS:ADD permission.

## Request Body

Required.

### application/json

Schema

```json
{
  "required": [
    "callbackUrl",
    "events",
    "name"
  ],
  "type": "object",
  "properties": {
    "callbackUrl": {
      "type": "string",
      "description": "HTTPS endpoint URL where webhook event notifications will be sent. Must be a valid HTTPS URL.",
      "example": "https://api.mycompany.com/webhooks/auth-events"
    },
    "enabled": {
      "type": "boolean",
      "description": "Indicates whether the webhook is active and will receive event notifications. Disabled webhooks will not receive any events.",
      "example": true
    },
    "events": {
      "type": "array",
      "description": "List of event types that will trigger this webhook. If not specified, all available events will be sent.",
      "items": {
        "required": [
          "type"
        ],
        "type": "object",
        "properties": {
          "filter": {
            "type": "string",
            "description": "Subset of resource, or group IDs of the webhook event. All resources are selected by default if this parameter is not specified.",
            "example": "[{\"enrollmentDesignId\":\"fd1d1b86-d258-4332-ad89-ead30d2dae7f\"}]"
          },
          "id": {
            "type": "string",
            "description": "The ID of the webhook event. This value is not needed when creating/updating a webhook."
          },
          "type": {
            "type": "string",
            "description": "The event type set to trigger the webhook.",
            "example": "user.created",
            "enum": [
              "user.created",
              "user.updated",
              "user.deleted",
              "user.registration.completed",
              "authentication.succeeded",
              "authentication.failed",
              "password.updated",
              "magiclink.email.sent",
              "grid.created",
              "grid.email.sent",
              "grid.password.email.sent",
              "passkey.created",
              "passkey.updated",
              "passkey.deleted",
              "passkey.registration.failed",
              "kba.question.created",
              "token.created",
              "token.activated",
              "token.activated.online",
              "token.seed.rotated",
              "hardware.token.assigned",
              "face.biometric.created",
              "credential.create",
              "credential.update",
              "credential.delete",
              "credential.print"
            ]
          }
        },
        "description": "Information returned about the events of a webhook.",
        "title": "WebhookEvent"
      }
    },
    "expiry": {
      "maximum": 1000,
      "minimum": 0,
      "type": "integer",
      "description": "How long to keep the webhook alive for <b>(in days)</b>. Value of 0 means no expiration. Once a webhook has reached expiry, it will be marked as <b>disabled</b>. This parameter is optional and is not set by default.",
      "format": "int32",
      "example": 90
    },
    "name": {
      "type": "string",
      "description": "Descriptive name for the webhook to help identify its purpose.",
      "example": "User Authentication Events Webhook"
    }
  },
  "description": "Parameters including the callback URL and list of events to trigger the webhook.",
  "title": "WebhookParms"
}
```

## Responses

### 200

Successful

#### application/json

Schema

```json
{
  "required": [
    "callbackUrl",
    "enabled",
    "id"
  ],
  "type": "object",
  "properties": {
    "callbackUrl": {
      "type": "string",
      "description": "HTTPS endpoint URL where webhook event notifications will be sent. Must be a valid HTTPS URL.",
      "example": "https://api.mycompany.com/webhooks/auth-events"
    },
    "enabled": {
      "type": "boolean",
      "description": "Indicates whether the webhook is active and will receive event notifications. Disabled webhooks will not receive any events.",
      "example": true
    },
    "events": {
      "type": "array",
      "description": "List of event types that will trigger this webhook. If not specified, all available events will be sent.",
      "items": {
        "required": [
          "type"
        ],
        "type": "object",
        "properties": {
          "filter": {
            "type": "string",
            "description": "Subset of resource, or group IDs of the webhook event. All resources are selected by default if this parameter is not specified.",
            "example": "[{\"enrollmentDesignId\":\"fd1d1b86-d258-4332-ad89-ead30d2dae7f\"}]"
          },
          "id": {
            "type": "string",
            "description": "The ID of the webhook event. This value is not needed when creating/updating a webhook."
          },
          "type": {
            "type": "string",
            "description": "The event type set to trigger the webhook.",
            "example": "user.created",
            "enum": [
              "user.created",
              "user.updated",
              "user.deleted",
              "user.registration.completed",
              "authentication.succeeded",
              "authentication.failed",
              "password.updated",
              "magiclink.email.sent",
              "grid.created",
              "grid.email.sent",
              "grid.password.email.sent",
              "passkey.created",
              "passkey.updated",
              "passkey.deleted",
              "passkey.registration.failed",
              "kba.question.created",
              "token.created",
              "token.activated",
              "token.activated.online",
              "token.seed.rotated",
              "hardware.token.assigned",
              "face.biometric.created",
              "credential.create",
              "credential.update",
              "credential.delete",
              "credential.print"
            ]
          }
        },
        "description": "Information returned about the events of a webhook.",
        "title": "WebhookEvent"
      }
    },
    "expired": {
      "type": "boolean",
      "description": "Indicates whether the webhook has passed its expiry date and is no longer active.",
      "example": false
    },
    "expiryDate": {
      "type": "string",
      "description": "Timestamp indicating when the webhook will automatically expire and stop receiving events. Null indicates no expiration.",
      "example": "2025-12-31T23:59:59"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier for the webhook. This value is automatically generated upon webhook creation and cannot be modified.",
      "example": "wh_1a2b3c4d5e6f7g8h"
    },
    "name": {
      "type": "string",
      "description": "Descriptive name for the webhook to help identify its purpose.",
      "example": "User Authentication Events Webhook"
    },
    "token": {
      "type": "string",
      "description": "Secure authentication token used to verify webhook request authenticity. Use this token to validate incoming webhook requests.",
      "example": "whsec_3f8a9b2c1d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
    }
  },
  "description": "Webhook configuration returned by the API.",
  "title": "Webhook"
}
```

### 400

Bad Request

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 401

Access denied

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 403

Forbidden

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 404

Not Found

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 409

Conflict

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

## Security

Requirements

```json
[
  {
    "AdminAPIAuthentication": [
      "WEBHOOKS:ADD"
    ]
  }
]
```