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"

Batch create or update objectsCreates or updates up to 100 objects in a single request. Ideal for scheduled syncs (e.g., pushing data every 5 minutes). **Matching behavior:** - If `match_by` and `match_value` are provided and a record is found, it is **updated**. - If no match is found (or `match_by` is omitted), a new record is **created**. - For contacts and companies, creation also deduplicates automatically (by email/domain). **Error handling:** - Each object is processed independently — a failure on one object does not abort the batch. - Check the `results` array for per-object status. Objects are processed sequentially to ensure correct deduplication.

⌘I

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"
}

Overview

Objects

Views

Batch

Webhooks

Trigger a skill via webhook

Authorizations

Headers

Path Parameters

Body

Response