> ## Documentation Index
> Fetch the complete documentation index at: https://docs.item.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.




## OpenAPI

````yaml /openapi.yaml post /api/webhooks/{skillId}
openapi: 3.1.0
info:
  title: item API
  description: >
    The item API provides full CRUD access to your organization's data — People,
    Companies, and Custom Objects.


    Use it to:

    - Push structured data into item on a schedule

    - Sync custom field values across your stack

    - Pull filtered records and pre-configured views

    - Use item as your source of truth for customer data


    ## Authentication


    All requests require an API key passed in the `x-api-key` header.


    You can generate an API key from **Settings > System > API Key** in your
    item workspace.


    ```bash

    curl -H "x-api-key: sk_live_..." https://app.useitem.io/api/objects/contacts

    ```
  version: 1.0.0
  contact:
    name: item Support
servers:
  - url: https://app.useitem.io
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - apiKey: []
tags:
  - name: Objects
    description: Create, read, update, and delete People, Companies, and Custom Objects.
  - name: Schema
    description: Discover available object types and their field definitions.
  - name: Users
    description: List organization members and their access levels.
  - name: Views
    description: List and execute pre-configured views to pull filtered data.
  - name: Batch
    description: Bulk create or update objects for high-frequency sync operations.
  - name: Webhooks
    description: Trigger skills (AI agents) via HTTP webhooks from external systems.
paths:
  /api/webhooks/{skillId}:
    parameters:
      - name: skillId
        in: path
        required: true
        description: >-
          The ID of the skill to trigger. The skill must have a webhook trigger
          configured and be in "live" status.
        schema:
          type: string
          format: uuid
    post:
      tags:
        - Webhooks
      summary: Trigger a skill via webhook
      description: >
        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.
      operationId: triggerSkillWebhook
      parameters:
        - name: x-webhook-signature
          in: header
          required: false
          description: |
            Optional HMAC-SHA256 signature for payload verification.
            Format: `sha256={hex_signature}`.
            Computed as `HMAC-SHA256(raw_json_body, api_key)`.
          schema:
            type: string
          example: sha256=a1b2c3d4e5f6...
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: Any JSON object. Passed to the skill as input context.
            example:
              event: new_lead
              user:
                email: alex@acme.com
                name: Alex Johnson
              source: landing_page
              timestamp: '2025-10-20T12:00:00Z'
      responses:
        '200':
          description: Skill triggered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  skillRunId:
                    type: string
                    format: uuid
                    description: ID of the created skill run
                    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  message:
                    type: string
                    example: Webhook received and skill triggered successfully
        '400':
          description: Skill not active or no webhook trigger configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_active:
                  value:
                    error: 'Skill is not active (status: paused)'
                no_trigger:
                  value:
                    error: >-
                      No webhook trigger configured for this skill. Please
                      create a webhook trigger first.
                invalid_payload:
                  value:
                    error: Payload must be a JSON object
        '401':
          description: Invalid or missing API key, or invalid webhook signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Skill does not belong to your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Skill not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Payload too large (max 1MB)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          example: Object not found
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your organization's API key (starts with `sk_live_`)

````