Skip to Content
PlatformWebhooks and Callbacks

Webhooks and Callbacks

Beav3r can send the final terminal decision for a request back into your system over HTTP.

Use https://staging.server.beav3r.ai for staging examples and https://server.beav3r.ai for the hosted production server.

Use callbacks when your system or workflow needs to react after a request is:

  • approved
  • denied
  • expired

Where callback URLs come from

There are two places to configure a callback target:

  1. the project-level Callback URL in the dashboard
  2. a per-request callbackUrl on the action itself

If a request includes callbackUrl, that request-specific URL wins.

If not, Beav3r falls back to the project’s Callback URL.

Typical uses

Callbacks are useful for:

  • continuing your workflow after approval
  • updating an internal ledger or payout job
  • closing an external review task
  • notifying your system that a request timed out or was denied

SDK example

With @beav3r/sdk, pass callbackUrl when creating the action:

import { Beav3r } from '@beav3r/sdk'
 
const client = new Beav3r({
  baseUrl: 'https://staging.server.beav3r.ai',
  apiKey: process.env.BEAV3R_API_KEY!,
  agentId: 'treasury_payout_agent'
})
 
const result = await client.guard({
  actionType: 'payments.send_usdt',
  payload: {
    amount: 4200,
    recipient: '0x1111111111111111111111111111111111111111'
  },
  attributes: {
    amount: 4200,
    merchant_name: 'Treasury Ops'
  },
  callbackUrl: 'https://example.com/beav3r/callbacks'
})

Delivery model

Beav3r sends callbacks as POST requests with:

  • Content-Type: application/json
  • idempotency-key: terminal:<actionHash>:<status>

Delivery is considered successful when your callback endpoint returns a 2xx response.

If delivery fails, Beav3r retries automatically with backoff before finally marking the callback as failed.

Callback payload

The callback body includes the final action state and enough identifiers to correlate it back into your system.

Typical payload:

{
  "eventType": "action.terminal",
  "requestId": "act_demo_123",
  "actionHash": "a741740cadadc260ca7e6101b0be43af5328a0d9c95bc7665a8f837c860df4",
  "projectId": "proj_123",
  "actionType": "payments.send_usdt",
  "agentId": "Treasury payout agent",
  "status": "approved",
  "createdAt": 1775581986,
  "updatedAt": 1775581998,
  "reason": "Amount exceeds approval threshold",
  "signature": "base64-signature",
  "approver": {
    "deviceId": "dev_123",
    "publicKey": "base64-public-key",
    "assurance": "biometric"
  }
}

Depending on the request, Beav3r may also include:

  • originId
  • apiKeyId
  • targetUserId
  • targetExternalAccountId

Receiving service requirements

A good callback endpoint should:

  • verify the request is expected
  • handle duplicate deliveries safely using the idempotency key
  • map requestId or actionHash back to your workflow
  • treat callback handling as asynchronous work rather than blocking user traffic

Local and staging notes

For local development, callbacks can point at a local HTTP target.

For production, use a stable, publicly reachable callback endpoint for your system rather than a local or private development address.

Policy Scope BasicsSigners