Webhooks

Trigger a skill via webhook

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.

POST

api

webhooks

{skillId}

Trigger a skill via webhook

curl --request POST \
  --url https://app.useitem.io/api/webhooks/{skillId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "event": "new_lead",
  "user": {
    "email": "alex@acme.com",
    "name": "Alex Johnson"
  },
  "source": "landing_page",
  "timestamp": "2025-10-20T12:00:00Z"
}
'

{
  "success": true,
  "skillRunId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Webhook received and skill triggered successfully"
}

Authorizations

x-api-key

string

header

required

Your organization's API key (starts with sk_live_)

Headers

x-webhook-signature

string

Optional HMAC-SHA256 signature for payload verification. Format: sha256={hex_signature}. Computed as HMAC-SHA256(raw_json_body, api_key).

Path Parameters

skillId

string<uuid>

required

The ID of the skill to trigger. The skill must have a webhook trigger configured and be in "live" status.

Body

application/json

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

Response

Skill triggered successfully

success

boolean

Example:

true

skillRunId

string<uuid>

ID of the created skill run

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

message

string

Example:

"Webhook received and skill triggered successfully"

List organization usersReturns all users in the organization with their IDs and access levels. Useful for mapping `owned_by_user_id` values or assigning records to users.

Trigger a skill via webhook

curl --request POST \
  --url https://app.useitem.io/api/webhooks/{skillId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "event": "new_lead",
  "user": {
    "email": "alex@acme.com",
    "name": "Alex Johnson"
  },
  "source": "landing_page",
  "timestamp": "2025-10-20T12:00:00Z"
}
'

{
  "success": true,
  "skillRunId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Webhook received and skill triggered successfully"
}