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

# Webhooks and Devhooks

> How external services communicate with Blink agents via webhooks, and how devhooks work during local development.

## Webhooks

Webhooks allow external services like Slack and GitHub to send events to your Blink agents.

### How Webhooks Work

1. External service (Slack, GitHub) sends HTTP request to Blink Server
2. Server routes the event to the appropriate agent deployment
3. Agent processes the event and responds

### Request Routing

Each deployment has a stable `request_id`. The server routes incoming webhooks based on this ID:

* If `wildcardAccessUrl` is configured, webhooks use subdomain routing: `{request_id}.your-domain`
* Otherwise, path routing is used: `/api/webhook/{request_id}/{path}`

Requests are proxied to the deployment's direct access URL (the docker container's external API port on localhost) - with an invocation token.

### Webhook URL Format

Each agent has a unique webhook URL:

```
https://<server-url>/api/agents/<agent-webhook-id>/<integration>/<path>
```

For example:

* Slack events: `https://blink.example.com/api/agents/abc123/slack/events`
* GitHub webhooks: `https://blink.example.com/api/agents/abc123/github/webhook`

### Wildcard Subdomain Routing

For a more secure setup, you can configure wildcard subdomain routing:

```bash theme={null}
# Server configuration
BLINK_WILDCARD_ACCESS_URL=*.dev.example.com
```

With this configured, each agent gets a unique subdomain:

```
https://<agent-webhook-id>.dev.example.com
```

This requires:

* A wildcard DNS record pointing `*.dev.example.com` to your server
* A wildcard TLS certificate for `*.dev.example.com`

### Webhook Sequence

```mermaid theme={null}
sequenceDiagram
  participant Source as Slack or GitHub
  participant Server as Blink Server
  participant DB as Postgres
  participant Agent as Agent Container
  participant Devhook as Devhook WS

  Source->>Server: POST webhook (access URL)
  Server->>DB: lookup request_id
  alt deployment found
    Server->>Agent: proxy request (x-blink-invocation-token)
    Agent-->>Server: response
    Server-->>Source: response
  else no deployment
    Server->>Devhook: proxy if connected
    Devhook-->>Server: response
    Server-->>Source: response or 404
  end
```

## Devhooks

Devhooks let you receive webhooks on your local machine during development. They create a tunnel from the Blink Server to your local agent.

Devhook is a WebSocket bridge used by the CLI for local agent development. If no deployment exists for a `request_id`, the server attempts to proxy the request to a devhook session instead.

### How Devhooks Work

1. `blink dev` establishes a tunnel connection to the server
2. The devhook gets assigned a unique URL on the server to receive webhooks
3. Incoming webhook requests are tunneled through the connection
4. Your local agent receives the request as if it came directly

### Using Devhooks

Devhooks are created automatically when you run:

```bash theme={null}
blink dev
```

The CLI displays your devhook URL, which you can use to configure external services during development.

### Wildcard Subdomain Routing

Webhook wildcard subdomain routing applies to devhooks as well.