API reference · v1
Webhooks
Manage outgoing webhooks.
List webhooks
GET
/v1/webhooksQuery parameters
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/webhooks' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "wh_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"url": "https://example.com",
"trigger": "contact upserted",
"emailEventTypes": [
"scheduled"
],
"schemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"condition": {
"type": "none"
},
"status": "live",
"totalCalls": 0,
"failedCalls": 0,
"failedCallsInARow": 0,
"lastCalledAt": "2025-01-15T10:30:00.000Z",
"lastCallErrorMessage": "string",
"integrationVendorName": "string"
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of webhooks.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Create a webhook
POST
/v1/webhooksCreates an outgoing webhook and returns signatureVerificationSecret. Store the secret securely; normal GET/list responses omit it. Supports Idempotency-Key, including replay of the original secret-bearing response. A custom filter generates through AI from requirements, uses the ai rate bucket and credits, and exposes only its description. Schema accepts an id or slug and must match the trigger. Deliveries retry network failures, HTTP 408, 429, and 5xx with bounded backoff; deduplicate their stable X-Webhook-ID. Delivery URL and secret are captured when enqueued, so queued deliveries can use earlier settings. Errors include invalid_webhook, schema_not_found, segment_not_found, and insufficient_credits.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json. A body is required.
- Name
url- Type
- string (uri)
- Requirement
- Required
- Description
- See the request example and OpenAPI schema for this field.
- Name
trigger- Type
- string
- Requirement
- Required
- Description
- Allowed values: "contact upserted", "contact deleted", "object upserted", "object deleted", "event fired", "email event".
- Name
emailEventTypes- Type
- string[]
- Description
- Required and non-empty only when trigger is
email event.
- Name
schemaId- Type
- string | null
- Description
- A schema id or slug. Required for every trigger except
email event.
- Name
condition- Type
- object
- Description
- The filter condition to create or update a webhook with. A
custom filtercondition generates via AI fromrequirements(billed,airate bucket).
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/webhooks' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/maxclicks",
"trigger": "contact upserted",
"schemaId": "customers",
"condition": {
"type": "none"
}
}'Response
{
"data": {
"id": "wh_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"url": "https://example.com",
"trigger": "contact upserted",
"emailEventTypes": [
"scheduled"
],
"schemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"condition": {
"type": "none"
},
"status": "live",
"totalCalls": 0,
"failedCalls": 0,
"failedCallsInARow": 0,
"lastCalledAt": "2025-01-15T10:30:00.000Z",
"lastCallErrorMessage": "string",
"integrationVendorName": "string",
"signatureVerificationSecret": "string"
},
"warnings": []
}Status codes
- 201The created webhook, including its signing secret.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 402Insufficient credits (
insufficient_credits) for an AI-generation call or a schema with AI auto-fill, or the space's email allowance is exhausted (email_limit_reached). - 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Get a webhook
GET
/v1/webhooks/{id}Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The webhook id.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/webhooks/wh_BcwDvBUeSaSDILA5tHgpmU7I' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"id": "wh_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"url": "https://example.com",
"trigger": "contact upserted",
"emailEventTypes": [
"scheduled"
],
"schemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"condition": {
"type": "none"
},
"status": "live",
"totalCalls": 0,
"failedCalls": 0,
"failedCallsInARow": 0,
"lastCalledAt": "2025-01-15T10:30:00.000Z",
"lastCallErrorMessage": "string",
"integrationVendorName": "string"
},
"warnings": []
}Status codes
- 200The webhook.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Update a webhook
PATCH
/v1/webhooks/{id}Updates url, emailEventTypes, condition, and/or status (live or paused); at least one is required. Trigger and schema cannot change. A custom filter uses AI and credits. Supports Idempotency-Key. Setting live clears the circuit-breaker count. Already enqueued deliveries keep their captured URL and signing secret. Queued deliveries observed while paused are suppressed rather than held for later replay. Integration-owned webhooks cannot be changed.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The webhook id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json. A body is required.
At least one field must be provided. Trigger and schema are not updatable.
- Name
url- Type
- string (uri)
- Description
- See the request example and OpenAPI schema for this field.
- Name
emailEventTypes- Type
- string[]
- Description
- See the request example and OpenAPI schema for this field.
- Name
condition- Type
- object
- Description
- The filter condition to create or update a webhook with. A
custom filtercondition generates via AI fromrequirements(billed,airate bucket).
- Name
status- Type
- string
- Description
- Allowed values: "live", "paused".
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/webhooks/wh_BcwDvBUeSaSDILA5tHgpmU7I' \
-X PATCH \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{
"status": "live"
}'Response
{
"data": {
"id": "wh_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"url": "https://example.com",
"trigger": "contact upserted",
"emailEventTypes": [
"scheduled"
],
"schemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"condition": {
"type": "none"
},
"status": "live",
"totalCalls": 0,
"failedCalls": 0,
"failedCallsInARow": 0,
"lastCalledAt": "2025-01-15T10:30:00.000Z",
"lastCallErrorMessage": "string",
"integrationVendorName": "string"
},
"warnings": []
}Status codes
- 200The updated webhook.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 402Insufficient credits (
insufficient_credits) for an AI-generation call or a schema with AI auto-fill, or the space's email allowance is exhausted (email_limit_reached). - 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Delete a webhook
DELETE
/v1/webhooks/{id}Deletes a webhook. Supports Idempotency-Key. Missing webhooks return webhook_not_found; integration-owned webhooks cannot be deleted.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The webhook id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/webhooks/wh_BcwDvBUeSaSDILA5tHgpmU7I' \
-X DELETE \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}"Response
{
"data": {
"id": "wh_BcwDvBUeSaSDILA5tHgpmU7I",
"deleted": true
},
"warnings": []
}Status codes
- 200The webhook was deleted.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Rotate a webhook secret
POST
/v1/webhooks/{id}/rotate-secretCreates a new signing secret and returns it with the webhook id and updatedAt. Store it securely. Supports Idempotency-Key: retry the same key to recover the original secret-bearing response instead of rotating again. Normal reads never reveal the secret. Already enqueued deliveries retain their captured secret and URL, including retries; keep the previous verification secret until those deliveries drain. Integration-owned webhooks cannot be rotated.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The webhook id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/webhooks/wh_BcwDvBUeSaSDILA5tHgpmU7I/rotate-secret' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}"Response
{
"data": {
"id": "wh_BcwDvBUeSaSDILA5tHgpmU7I",
"signatureVerificationSecret": "string",
"updatedAt": "2025-01-15T10:30:00.000Z"
},
"warnings": []
}Status codes
- 200The new signing secret.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.