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

# Connectors and Webhooks

Create connector records, keep credentials out of workflow payloads, and subscribe to signed execution webhooks.

Connectors and execution webhooks solve opposite sides of integration work. Connectors let B3OS call external systems. Execution webhooks let your systems receive signed B3OS run events.

**Connector and webhook integration**

**Connector**
  **Workflow node**
  **Provider API**
  **Execution webhook**
  **Your backend**
  **selected by node**
  **provider call**
  **event**
  **signed POST**

## Create a Connector

The connector `type` decides the required data shape. Use connector-type discovery in the app or API before writing provisioning code.

```bash
curl -X POST "https://api.b3os.org/v1/connectors" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Telegram bot",
    "type": "telegram-bot",
    "description": "Bot used for production workflow alerts.",
    "data": {}
  }'
```

**Provision from a trusted backend**

Connector data is provider-specific and should come from a secure backend or the B3OS app, not shell history or copied
  secrets in documentation.

## Use a Connector in a Node

```json
{
  "type": "send-telegram-message",
  "connector": {
    "type": "telegram-bot",
    "id": "conn_telegram_bot"
  },
  "payload": {
    "chatId": "123456789",
    "text": "Workflow {{$nodes.format.result.formatted}}"
  },
  "children": []
}
```

## Subscribe to Execution Events

```bash
curl -X POST "https://api.b3os.org/v1/execution-webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production run events",
    "url": "https://example.com/b3os/events",
    "description": "Receives workflow run and node execution events.",
    "subscribedEventTypes": [
      "run.completed",
      "run.failed",
      "node.failed"
    ],
    "maxRetries": 5
  }'
```

## Delivery Operations

| Task | Endpoint |
| --- | --- |
| List endpoints | ` GET /v1/execution-webhooks ` |
| Disable an endpoint | ` POST /v1/execution-webhooks/{id}/disable ` |
| Enable an endpoint | ` POST /v1/execution-webhooks/{id}/enable ` |
| Rotate signing secret | ` POST /v1/execution-webhooks/{id}/regenerate-secret ` |
| List deliveries | ` GET /v1/execution-webhooks/deliveries ` |
| Replay a delivery | ` POST /v1/execution-webhooks/deliveries/{id}/replay ` |

## Verify the Signature

See [Execution Hooks](/api/execution-hooks) for signing headers, event fields, retry behavior, and verification guidance.

**[Connector docs](/platform/connectors)**

Learn connector types, credential handling, and node references.
  **[Execution webhooks](/platform/webhooks-executions)**

Learn event delivery, retries, observability, and replay behavior.