Sign in

Create Superagent webhook

<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

Path parameters

agent_idstring required

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

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

Changed in 1 of the 27 revisions of this API.1

Of the 27 revisions, 1 has no diff computed.