> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Superagent webhook
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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](/api-reference/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.
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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/agents/{agent_id}/webhooks
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/agents/{agent_id}/webhooks:
post:
summary: Create Superagent webhook
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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](/api-reference/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.
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.
operationId: create_webhook_api_agents__agent_id__webhooks_post
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
description: >-
ID of the Superagent. It's the agent's app ID, shown in the
agent's developer settings.
title: Agent Id
description: >-
ID of the Superagent. It's the agent's app ID, shown in the agent's
developer settings.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookPayload'
responses:
'200':
description: The new webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/SuperagentWebhookWithSecret'
'400':
description: >-
`agent_id` belongs to an app that isn't a Superagent, or the agent
already has 5 webhooks.
'401':
description: Missing or invalid credentials.
'402':
description: Agent webhooks need the Builder plan or higher.
'403':
description: >-
You aren't an editor of this agent, you're a viewer in its
workspace, your API key is read-only, or you used a workspace API
key.
'404':
description: Agent not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded (100 requests per minute).
components:
schemas:
CreateWebhookPayload:
properties:
target_url:
type: string
title: Target Url
description: Public HTTPS URL that receives the events.
example: https://example.com/hooks/agent
events:
items:
type: string
type: array
title: Events
description: >-
Events to receive. One or more of `message.created` and
`message.completed`.
example:
- message.completed
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Your label for the webhook.
example: CRM sync
generate_secret:
type: boolean
title: Generate Secret
description: >-
`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.
default: false
example: true
type: object
required:
- target_url
title: CreateWebhookPayload
SuperagentWebhookWithSecret:
properties:
id:
type: string
title: Id
description: ID of the webhook.
example: 68a1d0f4f0b9d3002e7a5c52
target_url:
type: string
title: Target Url
description: HTTPS URL Base44 sends the events to.
example: https://example.com/hooks/agent
events:
items:
type: string
enum:
- message.created
- message.completed
type: array
title: Events
description: >-
Events the webhook receives. `message.created` fires when a message
is added to a conversation, and `message.completed` when the agent
finishes a reply.
example:
- message.completed
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Your label for the webhook, or `null` when it has none.
example: CRM sync
has_secret:
type: boolean
title: Has Secret
description: >-
Whether deliveries are signed. When `true`, each delivery carries an
`X-Base44-Signature` header, an HMAC-SHA256 of the body.
example: true
last_trigger_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Trigger Time
description: >-
Time of the last delivery attempt, successful or not, as a UTC
timestamp in ISO 8601 format, or `null` before the first one.
example: '2026-08-02T14:30:00Z'
last_error:
anyOf:
- $ref: '#/components/schemas/SuperagentWebhookError'
- type: 'null'
description: >-
What went wrong on the last failed delivery, or `null` when the last
delivery succeeded or none has failed.
consecutive_failures:
type: integer
title: Consecutive Failures
description: >-
Deliveries that failed in a row. After 20, Base44 turns the webhook
off and sets `disabled_at`.
example: 0
disabled_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Disabled At
description: >-
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](/api-reference/update-superagent-webhook).
example: '2026-08-03T08:00:00Z'
created_date:
type: string
format: date-time
title: Created Date
description: Time the webhook was created, as a UTC timestamp in ISO 8601 format.
example: '2026-08-01T09:15:00Z'
updated_date:
type: string
format: date-time
title: Updated Date
description: >-
Time the webhook last changed, as a UTC timestamp in ISO 8601
format.
example: '2026-08-02T14:30:00Z'
secret:
anyOf:
- type: string
- type: 'null'
title: Secret
description: >-
The signing secret, returned only in the response that generates it.
Store it, because no other response shows it again.
example: Rk3x9QeN0vZ8bL2mT6yH4cJ1wP7sD5fG0aX9kV3uE8o
type: object
required:
- id
- target_url
- events
- description
- has_secret
- last_trigger_time
- last_error
- consecutive_failures
- disabled_at
- created_date
- updated_date
title: SuperagentWebhookWithSecret
description: >-
A webhook subscription, with its signing secret when one was just
generated.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
SuperagentWebhookError:
properties:
message:
type: string
title: Message
description: What went wrong on the last delivery.
example: 'Non-2xx response: 500'
attempted_at:
type: string
format: date-time
title: Attempted At
description: Time of the failed delivery, as a UTC timestamp in ISO 8601 format.
example: '2026-08-02T14:30:00+00:00'
status_code:
anyOf:
- type: integer
- type: 'null'
title: Status Code
description: >-
HTTP status your endpoint answered with, when it answered with a
non-2xx status.
example: 500
response_body:
anyOf:
- type: string
- type: 'null'
title: Response Body
description: >-
Start of your endpoint's response body, up to 512 bytes, when it
answered with a non-2xx status.
example: Internal Server Error
error_type:
anyOf:
- type: string
- type: 'null'
title: Error Type
description: >-
Kind of failure when the request didn't get an answer, such as a
timeout or a refused connection.
example: ConnectTimeout
type: object
required:
- message
- attempted_at
title: SuperagentWebhookError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: 'Personal access token, sent as `Authorization: Bearer `.'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.