Callbacks HTTP API
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 supplies the credentials and entities.
Accept a signed inbound webhook for one configured connection
Section titled “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. |
Content-Type: application/json.
Result and recovery
Section titled “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.
Accept authenticated Slack interactive actions for a connection
Section titled “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. |
Content-Type: application/x-www-form-urlencoded.
| Field | Type | Usage |
|---|---|---|
payload (required) |
string |
Canonical message/request information inside a delivery envelope. |
Result and recovery
Section titled “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.
Accept authenticated Slack event callbacks
Section titled “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. |
Content-Type: application/json.
object. See the operation-specific result contract.
Result and recovery
Section titled “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.
Secret-authenticated private bot updates
Section titled “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. |
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
Section titled “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.
Ed25519-authenticated Discord interactions
Section titled “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. |
Content-Type: application/json.
object. See the operation-specific result contract.
Result and recovery
Section titled “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.