> ## 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.
# Update Superagent webhook
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Changes a Superagent's webhook.
Send only the fields you want to change. Send `description: null` to remove the label. `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.
`enabled: true` turns a webhook back on after Base44 turned it off for failing, and resets `consecutive_failures`. `enabled: false` turns it off. `signing: "rotate"` generates a new signing secret and returns it once in `secret`, and `signing: "disable"` stops signing deliveries.
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 patch /api/agents/{agent_id}/webhooks/{webhook_id}
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/{webhook_id}:
patch:
summary: Update Superagent webhook
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Changes a Superagent's webhook.
Send only the fields you want to change. Send `description: null` to
remove the label. `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.
`enabled: true` turns a webhook back on after Base44 turned it off for
failing, and resets `consecutive_failures`. `enabled: false` turns it
off. `signing: "rotate"` generates a new signing secret and returns it
once in `secret`, and `signing: "disable"` stops signing deliveries.
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: update_webhook_api_agents__agent_id__webhooks__webhook_id__patch
parameters:
- name: webhook_id
in: path
required: true
schema:
type: string
description: >-
ID of the webhook to change. Get it from [List Superagent
webhooks](/api-reference/list-superagent-webhooks).
title: Webhook Id
description: >-
ID of the webhook to change. Get it from [List Superagent
webhooks](/api-reference/list-superagent-webhooks).
example: 68a1d0f4f0b9d3002e7a5c52
- 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/UpdateWebhookPayload'
responses:
'200':
description: The updated webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/SuperagentWebhookWithSecret'
'400':
description: '`agent_id` belongs to an app that isn''t a Superagent.'
'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 or webhook 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:
UpdateWebhookPayload:
properties:
target_url:
anyOf:
- type: string
- type: 'null'
title: Target Url
description: New public HTTPS URL that receives the events.
example: https://example.com/hooks/agent-v2
events:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Events
description: >-
New set of events to receive. One or more of `message.created` and
`message.completed`.
example:
- message.created
- message.completed
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: New label for the webhook, or `null` to remove it.
example: CRM sync
enabled:
anyOf:
- type: boolean
- type: 'null'
title: Enabled
description: >-
`true` turns the webhook back on and resets `consecutive_failures`.
`false` turns it off.
example: true
signing:
anyOf:
- type: string
- type: 'null'
title: Signing
description: >-
`rotate` generates a new signing secret and returns it once in
`secret`. `disable` removes the secret, so deliveries are no longer
signed.
example: rotate
type: object
title: UpdateWebhookPayload
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.