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

# Webhooks

> Configure webhook endpoints for event automation

Webhooks allow external systems to trigger Kubiya actions when events occur. Use webhooks to:

* Start agent tasks from CI/CD pipelines
* Trigger workflows from monitoring alerts
* Integrate with ticketing systems
* Automate responses to external events

## Access

Webhook configuration may be available through:

* **Settings** menu
* **Organization** settings (user menu > Organization)
* **Infrastructure** > **Workflows** section

<Note>
  The exact location of webhook settings depends on your organization's configuration and access level.
</Note>

## Managing Webhooks

### Creating a Webhook

1. Click **+ Create Webhook**
2. Configure the webhook:
   * **Name** - Descriptive identifier
   * **Target** - Agent or Team to receive events
   * **Event Types** - Which events trigger the webhook
   * **Secret** - Optional secret for signature verification
3. Click **Create**
4. Copy the generated webhook URL

### Webhook Details

Each webhook displays:

| Field              | Description                       |
| ------------------ | --------------------------------- |
| **Name**           | Webhook identifier                |
| **URL**            | Endpoint to send events to        |
| **Target**         | Agent or Team that handles events |
| **Status**         | Active or Disabled                |
| **Created**        | Creation timestamp                |
| **Last Triggered** | Most recent invocation            |

### Testing a Webhook

1. Click the **Test** button on any webhook
2. Review the test payload
3. Click **Send Test**
4. Check the target agent's task kanban for the test task

## Webhook URL

The generated URL follows this pattern:

```
https://compose.kubiya.ai/api/webhooks/{webhook-id}
```

Use this URL as the destination in your external systems.

## Sending Events

### Basic Request

```bash theme={null}
curl -X POST https://compose.kubiya.ai/api/webhooks/{webhook-id} \
  -H "Content-Type: application/json" \
  -d '{"message": "Deploy to production", "environment": "prod"}'
```

### With Authentication

If you configured a secret:

```bash theme={null}
curl -X POST https://compose.kubiya.ai/api/webhooks/{webhook-id} \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-secret-here" \
  -d '{"message": "Deploy to production"}'
```

## Event Payload

The webhook payload is passed to the target agent as context:

```json theme={null}
{
  "message": "Your request or instruction",
  "environment": "production",
  "triggered_by": "CI/CD Pipeline",
  "metadata": {
    "commit": "abc123",
    "branch": "main"
  }
}
```

The `message` field becomes the primary instruction for the agent.

## Integration Examples

### GitHub Actions

```yaml theme={null}
- name: Trigger Kubiya Agent
  run: |
    curl -X POST ${{ secrets.KUBIYA_WEBHOOK_URL }} \
      -H "Content-Type: application/json" \
      -d '{
        "message": "Deploy ${{ github.sha }} to staging",
        "commit": "${{ github.sha }}",
        "branch": "${{ github.ref_name }}"
      }'
```

### PagerDuty

Configure PagerDuty to send alerts to your webhook URL. The alert details are passed to the agent for automated response.

### Slack Workflows

Create a Slack workflow that posts to your webhook URL when specific conditions are met.

## Security

### Webhook Secrets

Always use a webhook secret in production:

1. Generate a strong random secret
2. Configure it in the webhook settings
3. Include it in the `X-Webhook-Secret` header
4. Kubiya validates the secret before processing

### IP Allowlisting

For additional security, configure your firewall to only allow webhook calls from known sources.

### Payload Validation

Implement payload validation in your calling system to prevent injection attacks.

## Monitoring

### Webhook Logs

View recent webhook invocations:

* Timestamp
* Source IP
* Payload received
* Processing result
* Target agent response

### Failed Invocations

Check failed webhooks for:

* Invalid payloads
* Authentication failures
* Target agent errors
* Rate limiting

## Rate Limits

Webhooks have rate limits to prevent abuse:

* **Per webhook**: 100 requests per minute
* **Per organization**: 1000 requests per minute

Exceeding limits returns HTTP 429.

## Disabling Webhooks

To temporarily stop a webhook:

1. Find the webhook in the list
2. Toggle the **Status** to Disabled
3. The URL remains valid but requests are rejected

To permanently remove:

1. Click **Delete**
2. Confirm deletion

<Warning>
  Deleting a webhook invalidates its URL permanently. Update any external systems using it before deletion.
</Warning>

## Related Pages

* **[Agents](/core-concepts/agents)** - Configure agents that receive webhook events
* **[Task Kanban](/web-interface/task-kanban)** - View webhook-triggered tasks
* **[Background Jobs](/core-concepts/background-jobs)** - Schedule recurring tasks