---
title: "Trigger a skill via webhook"
method: POST
path: "/api/webhooks/{skillId}"
tags: ["Webhooks"]
---

# Trigger a skill via webhook

`POST /api/webhooks/{skillId}`

## Request

- Base URL: `https://app.useitem.io`
- URL: `https://app.useitem.io/api/webhooks/{skillId}`
- Auth: API key in header `x-api-key`

Sends a webhook payload to trigger a skill (AI agent) run. The skill must have a
webhook trigger configured and be in "live" status.

The entire JSON body is passed to the skill as input context, so you can send
any structured data your skill needs.

**Common use cases:**
- React to events from external services (Stripe, TypeForm, etc.)
- Chain automation workflows across systems
- Trigger skills from your own application on custom events

**Optional signature verification:**
For enhanced security, include an HMAC-SHA256 signature in the `x-webhook-signature`
header. The signature is computed over the raw JSON body using your API key as the secret.

## Headers

- `x-webhook-signature` string

## Request body

- object: Any JSON object. Passed to the skill as input context.

## Response `200`

Skill triggered successfully

- object
  - `success` boolean
  - `skillRunId` string, uuid: ID of the created skill run
  - `message` string

## Other responses

- `400`: Skill not active or no webhook trigger configured
- `401`: Invalid or missing API key, or invalid webhook signature
- `403`: Skill does not belong to your organization
- `404`: Skill not found
- `413`: Payload too large (max 1MB)

---

[API](https://skmtc.dev/item/apis/item-api.md) - [All operations](https://skmtc.dev/item/apis/item-api/llms.txt) - [OpenAPI document](https://skmtc.dev/item/apis/item-api/revisions/05e6374d3922?raw)