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

import requests

url = "https://app.useitem.io/api/webhooks/{skillId}"

payload = {
    "event": "new_lead",
    "user": {
        "email": "alex@acme.com",
        "name": "Alex Johnson"
    },
    "source": "landing_page",
    "timestamp": "2025-10-20T12:00:00Z"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    event: 'new_lead',
    user: {email: 'alex@acme.com', name: 'Alex Johnson'},
    source: 'landing_page',
    timestamp: '2025-10-20T12:00:00Z'
  })
};

fetch('https://app.useitem.io/api/webhooks/{skillId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.useitem.io/api/webhooks/{skillId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'event' => 'new_lead',
    'user' => [
        'email' => 'alex@acme.com',
        'name' => 'Alex Johnson'
    ],
    'source' => 'landing_page',
    'timestamp' => '2025-10-20T12:00:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.useitem.io/api/webhooks/{skillId}"

	payload := strings.NewReader("{\n  \"event\": \"new_lead\",\n  \"user\": {\n    \"email\": \"alex@acme.com\",\n    \"name\": \"Alex Johnson\"\n  },\n  \"source\": \"landing_page\",\n  \"timestamp\": \"2025-10-20T12:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.useitem.io/api/webhooks/{skillId}")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event\": \"new_lead\",\n  \"user\": {\n    \"email\": \"alex@acme.com\",\n    \"name\": \"Alex Johnson\"\n  },\n  \"source\": \"landing_page\",\n  \"timestamp\": \"2025-10-20T12:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.useitem.io/api/webhooks/{skillId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event\": \"new_lead\",\n  \"user\": {\n    \"email\": \"alex@acme.com\",\n    \"name\": \"Alex Johnson\"\n  },\n  \"source\": \"landing_page\",\n  \"timestamp\": \"2025-10-20T12:00:00Z\"\n}"

response = http.request(request)
puts response.read_body

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

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

import requests

url = "https://app.useitem.io/api/webhooks/{skillId}"

payload = {
    "event": "new_lead",
    "user": {
        "email": "alex@acme.com",
        "name": "Alex Johnson"
    },
    "source": "landing_page",
    "timestamp": "2025-10-20T12:00:00Z"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    event: 'new_lead',
    user: {email: 'alex@acme.com', name: 'Alex Johnson'},
    source: 'landing_page',
    timestamp: '2025-10-20T12:00:00Z'
  })
};

fetch('https://app.useitem.io/api/webhooks/{skillId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.useitem.io/api/webhooks/{skillId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'event' => 'new_lead',
    'user' => [
        'email' => 'alex@acme.com',
        'name' => 'Alex Johnson'
    ],
    'source' => 'landing_page',
    'timestamp' => '2025-10-20T12:00:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.useitem.io/api/webhooks/{skillId}"

	payload := strings.NewReader("{\n  \"event\": \"new_lead\",\n  \"user\": {\n    \"email\": \"alex@acme.com\",\n    \"name\": \"Alex Johnson\"\n  },\n  \"source\": \"landing_page\",\n  \"timestamp\": \"2025-10-20T12:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.useitem.io/api/webhooks/{skillId}")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event\": \"new_lead\",\n  \"user\": {\n    \"email\": \"alex@acme.com\",\n    \"name\": \"Alex Johnson\"\n  },\n  \"source\": \"landing_page\",\n  \"timestamp\": \"2025-10-20T12:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.useitem.io/api/webhooks/{skillId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event\": \"new_lead\",\n  \"user\": {\n    \"email\": \"alex@acme.com\",\n    \"name\": \"Alex Johnson\"\n  },\n  \"source\": \"landing_page\",\n  \"timestamp\": \"2025-10-20T12:00:00Z\"\n}"

response = http.request(request)
puts response.read_body

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

Overview

MCP

Objects

Views

Batch

Schema

Users

Webhooks

Trigger a skill via webhook

Authorizations

Headers

Path Parameters

Body

Response