Skip to main content
POST
/
api
/
v1
/
agents
/
{agentId}
/
tasks
/
{taskId}
/
webhooks
Register a webhook callback for terminal task events.
curl --request POST \
  --url https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks/{taskId}/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "token": "<string>",
  "secret": "<string>"
}
'
{
  "success": true,
  "data": {
    "webhook_id": "<string>",
    "task_id": "<string>",
    "url": "<string>",
    "has_secret": true,
    "created_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
Authorization
string
header
required

Pass a user JWT or a oag_ User API Key on the Authorization: Bearer <token> header. Both are validated by openapi-gateway against the Auth service.

Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.

Removed in v1.1.0: the legacy agents:* / tasks:* / files:* / instances:* scope set has been dropped together with the 403 insufficient_scope error. Existing oag_ keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passed scopes to createAPIKey should drop the argument. See the changelog at the bottom of this spec for the full migration note.

Path Parameters

​
agentId
string
required
Maximum string length: 128
​
taskId
string
required
Maximum string length: 128

Body

application/json
​
url
string<uri>
required

Absolute HTTPS endpoint to POST callbacks to. The receiver gets the protocol-specific payload (OpenAPI: a task event envelope; A2A: JSON-RPC StreamResponse; MCP: notification).

​
token
string

Optional bearer token sent as Authorization: Bearer <token> on each callback so the receiver can verify the call.

​
secret
string

P2-A — HMAC-SHA256 signing key. When set, the deliverer signs every callback body and emits X-BeeOS-Signature: t=<unix>,v1=<hex> where hex = hmac_sha256(secret, t || "." || body). The receiver should re-run the same HMAC to authenticate; mismatched timestamps (±5 min recommended tolerance) should be rejected to defend against replay.

Write-only. Never echoed on Get / List responses; the has_secret boolean on TaskWebhookResponse is the only observable signal. Rotate by Set-ing a fresh value; passing "" on update preserves the existing secret (use DELETE + re-register to clear).

Required string length: 16 - 256

Response

Webhook registered.

​
success
boolean
required
​
data
object
required