Webhooks — MDDB API

Webhook registration and management

List webhooks #

GET /v1/webhooks

List all registered webhooks.

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	List of registered webhooks	array of Webhook (application/json)
400	Webhooks are not initialized	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Register webhook #

POST /v1/webhooks

Register a new webhook to receive event notifications. This is a write-protected endpoint.

If collection is empty, the webhook will receive events for all collections.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: RegisterWebhookRequest

{
  "collection": "blog",
  "events": [
    "doc.added",
    "doc.updated"
  ],
  "url": "https://example.com/hook"
}

Responses #

Status	Description	Body
200	Webhook registered successfully	Webhook (application/json)
400	Invalid request	ErrorResponse (application/json)
403	Read-only mode	ErrorResponse (application/json)

Delete webhook #

POST /v1/webhooks/delete

Delete a registered webhook by its ID. This is a write-protected endpoint.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: DeleteWebhookRequest

{
  "id": "abc123"
}

Responses #

Status	Description	Body
200	Webhook deleted successfully	object (application/json)
400	Invalid request	ErrorResponse (application/json)
403	Read-only mode	ErrorResponse (application/json)