# Callbacks HTTP API

Inputs, results, permissions and errors for the callbacks endpoints.

Use the server URL of your own deployment. Worker examples require a currently valid bearer token; provider callbacks use native signatures. `REPLACE_WITH_RETURNED_ID` values refer to IDs obtained through setup or prior operations. [Headless setup](https://beepgrid.com/docs/start/headless.md) supplies the credentials and entities.

<a id="post-integrations-webhook-id"></a>

## Accept a signed inbound webhook for one configured connection

`POST /integrations/webhook/{id}`

Accept a signed inbound webhook for one configured connection.

**Authorization:** Provider callback. Use its native signature/secret verification, not a worker bearer token.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |
| `X-Beepgrid-Timestamp` | header (required) | Signed webhook timestamp used for replay protection. |
| `X-Beepgrid-Signature` | header (required) | Webhook HMAC signature over the documented timestamp and raw body. |
| `X-Beepgrid-Event-ID` | header (required) | Unique signed webhook event identity; stable across identical retries. |


### Input

Content-Type: `application/json`.

[SendInput](https://beepgrid.com/docs/reference/models/#sendinput)

### Result and recovery

SendResult: canonical conversation_id and messages. This signed callback supports ordinary messages, not implicit final approval.

Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.

Response media type: `application/json`. `object`. See the operation-specific result contract.


<a id="post-integrations-slack-id"></a>

## Accept authenticated Slack interactive actions for a connection

`POST /integrations/slack/{id}`

Accept authenticated Slack interactive actions for a connection.

**Authorization:** Provider callback. Use its native signature/secret verification, not a worker bearer token.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |
| `X-Slack-Request-Timestamp` | header (required) | Slack timestamp included in v0 signature verification and replay protection. |
| `X-Slack-Signature` | header (required) | Slack v0 HMAC signature verified with the connection signing secret. |


### Input

Content-Type: `application/x-www-form-urlencoded`.

| Field | Type | Usage |
| --- | --- | --- |
| `payload` (required) | `string` | Canonical message/request information inside a delivery envelope. |

### Result and recovery

Slack acknowledgment after canonical handling; current decision authority still applies.

Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.

Response media type: `application/json`. `object`. See the operation-specific result contract.


<a id="post-integrations-slack-id-events"></a>

## Accept authenticated Slack event callbacks

`POST /integrations/slack/{id}/events`

Accept authenticated Slack event callbacks.

**Authorization:** Provider callback. Use its native signature/secret verification, not a worker bearer token.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |
| `X-Slack-Request-Timestamp` | header (required) | Slack timestamp included in v0 signature verification and replay protection. |
| `X-Slack-Signature` | header (required) | Slack v0 HMAC signature verified with the connection signing secret. |


### Input

Content-Type: `application/json`.

`object`. See the operation-specific result contract.

### Result and recovery

Slack challenge or event acknowledgment with duplicate-event handling.

Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.

Response media type: `application/json`. `object`. See the operation-specific result contract.


<a id="post-integrations-telegram-id"></a>

## Secret-authenticated private bot updates

`POST /integrations/telegram/{id}`

Secret-authenticated private bot updates. Canonical message/decision, thread and dedup receipt commit before success. Same ID with changed content conflicts. See docs/TELEGRAM.md.

**Authorization:** Provider callback. Use its native signature/secret verification, not a worker bearer token.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |
| `X-Telegram-Bot-Api-Secret-Token` | header (required) | Telegram webhook secret token configured for this connection. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `update_id` (required) | `integer` | Telegram update identity used for canonical duplicate handling. minimum=0. |
| `message` | `object` | Safe human-readable API error message. |
| `callback_query` | `object` | Native Telegram callback query object, verified against the connection and linked person. |

### Result and recovery

A message receipt has conversation_id and message_count. A decision receipt has conversation_id, request_id and outcome (approved or denied). Ignored unsupported update categories return {ignored: true}. Each handled receipt follows durable commit.

Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.

Response media type: `application/json`. `object`. See the operation-specific result contract.


<a id="post-integrations-discord-id"></a>

## Ed25519-authenticated Discord interactions

`POST /integrations/discord/{id}`

Ed25519-authenticated Discord interactions. Bot DM commands, reply forms and versioned approvals only. Commits canonical actions and dedup receipt before acknowledgment. See docs/DISCORD.md.

**Authorization:** Provider callback. Use its native signature/secret verification, not a worker bearer token.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |
| `X-Signature-Timestamp` | header (required) | Discord request timestamp included in signature verification. |
| `X-Signature-Ed25519` | header (required) | Discord Ed25519 signature over timestamp and raw body, verified using the application public key. |


### Input

Content-Type: `application/json`.

`object`. See the operation-specific result contract.

### Result and recovery

Discord interaction response: type plus optional data in the native Discord schema. Canonical receipt metadata stays internal; do not expect a Beepgrid message object in this HTTP response.

Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.

Response media type: `application/json`. `object`. See the operation-specific result contract.