BAbase44

Create Superagent webhook

Changed on

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Subscribes a URL to a Superagent's conversation events.

events takes one or more of message.created, which fires when a message is added to a conversation, and message.completed, which fires when the agent finishes a reply. target_url has to be a public HTTPS URL. An agent can have up to 5 webhooks, and each call adds one, so retrying a create that may have succeeded can add a duplicate. Check List Superagent webhooks first.

Base44 sends each event once and doesn't retry a failed delivery. A failure is recorded in last_error and counts toward consecutive_failures.

Set generate_secret to true to sign deliveries. The response then carries secret, the only time Base44 shows it.

<Note>This endpoint accepts a personal API key or personal access token belonging to an editor of the agent. A read-only key is refused, and workspace API keys are not accepted.</Note>

post/api/agents/{agent_id}/webhooks

Request

  • Base URL
    https://app.base44.com
  • URL
    https://app.base44.com/api/agents/{agent_id}/webhooks
  • Auth
    HTTP bearer

Path parameters

agent_idstring required

ID of the Superagent. It's the agent's app ID, shown in the agent's developer settings.

Request body

target_urlstring required

Public HTTPS URL that receives the events.

eventsstring[]

Events to receive. One or more of message.created and message.completed.

descriptionstring nullable

Your label for the webhook.

generate_secretboolean

true makes Base44 generate an HMAC-SHA256 signing secret and return it once in the response. Deliveries are signed with an X-Base44-Signature header only when the webhook has a secret.

Example request

{
  "target_url": "https://example.com/hooks/agent",
  "events": [
    "message.completed"
  ],
  "description": "CRM sync",
  "generate_secret": true
}

Response

The new webhook.

idstring required

ID of the webhook.

target_urlstring required

HTTPS URL Base44 sends the events to.

eventsstring[] required

Events the webhook receives. message.created fires when a message is added to a conversation, and message.completed when the agent finishes a reply.

descriptionstring nullable required

Your label for the webhook, or null when it has none.

has_secretboolean required

Whether deliveries are signed. When true, each delivery carries an X-Base44-Signature header, an HMAC-SHA256 of the body.

last_trigger_timestring date-time nullable required

Time of the last delivery attempt, successful or not, as a UTC timestamp in ISO 8601 format, or null before the first one.

consecutive_failuresinteger required

Deliveries that failed in a row. After 20, Base44 turns the webhook off and sets disabled_at.

disabled_atstring date-time nullable required

Time the webhook was turned off, as a UTC timestamp in ISO 8601 format, or null while it's on. Turn it back on with enabled: true in Update Superagent webhook.

created_datestring date-time required

Time the webhook was created, as a UTC timestamp in ISO 8601 format.

updated_datestring date-time required

Time the webhook last changed, as a UTC timestamp in ISO 8601 format.

secretstring nullable

The signing secret, returned only in the response that generates it. Store it, because no other response shows it again.

Example response

{
  "id": "68a1d0f4f0b9d3002e7a5c52",
  "target_url": "https://example.com/hooks/agent",
  "events": [
    "message.completed"
  ],
  "description": "CRM sync",
  "has_secret": true,
  "last_trigger_time": "2026-08-02T14:30:00Z",
  "last_error": {
    "message": "Non-2xx response: 500",
    "attempted_at": "2026-08-02T14:30:00+00:00",
    "status_code": 500,
    "response_body": "Internal Server Error",
    "error_type": "ConnectTimeout"
  },
  "disabled_at": "2026-08-03T08:00:00Z",
  "created_date": "2026-08-01T09:15:00Z",
  "updated_date": "2026-08-02T14:30:00Z",
  "secret": "Rk3x9QeN0vZ8bL2mT6yH4cJ1wP7sD5fG0aX9kV3uE8o"
}

Changes