curl --request PATCH \
--url https://api.1-funnel.org/v1/businesses/{businessId}/webhook-endpoints/{endpointId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "disabled"
}
'{
"id": "018f3c4e-7b2a-7c3d-8e9f-eeeeeeeeeeee",
"business_id": "018f3c4e-7b2a-7c3d-8e9f-0123456789ab",
"url": "https://hooks.example.com/1funnel/webhooks-v2",
"description": "Production SMS delivery callbacks",
"status": "active",
"event_types": [
"sms.message.delivered.v1"
],
"created_at": "2026-10-13T09:00:00.000Z",
"updated_at": "2026-10-13T10:00:00.000Z"
}Update a webhook endpoint
Partial update. URL changes require destination security validation but not ownership reverification (DEC-WH-V01 deferred). Does not return secrets.
curl --request PATCH \
--url https://api.1-funnel.org/v1/businesses/{businessId}/webhook-endpoints/{endpointId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "disabled"
}
'{
"id": "018f3c4e-7b2a-7c3d-8e9f-eeeeeeeeeeee",
"business_id": "018f3c4e-7b2a-7c3d-8e9f-0123456789ab",
"url": "https://hooks.example.com/1funnel/webhooks-v2",
"description": "Production SMS delivery callbacks",
"status": "active",
"event_types": [
"sms.message.delivered.v1"
],
"created_at": "2026-10-13T09:00:00.000Z",
"updated_at": "2026-10-13T10:00:00.000Z"
}Authorizations
OAuth 2.0 Client Credentials for the External Integration API (ADR-015, ADR-023).
Client authentication: HTTP Basic (client_secret_basic).
Access-token audience: 1funnel-external-api.
The tokenUrl below is the production target. Sandbox uses a different
host. OpenAPI cannot bind tokenUrl to the selected servers entry; see
x-1funnel-oauth on the root document and the authentication guide when published.
Coarse OAuth scopes (if any) are token-level vocabulary (ADR-013 IA-06). They
are not the ADR-022 resource permission catalogue. Resource permissions
are enforced after token validation via application-to-business grants
(ADR-016) and are documented per operation with x-required-permissions.
These URLs are architecture targets. They are not claimed to be deployed or generally available.
Headers
Request correlation identifier (STD-API-01 D12). Clients may supply a value
of 1–128 characters matching A-Za-z0-9._-. Missing or invalid values are
replaced by a server-generated identifier. Distinct from W3C traceparent,
resource ids, Idempotency-Key, and webhook event ids.
1 - 128^[A-Za-z0-9._-]+$"req_01HZX3K9EXAMPLE"
Path Parameters
Business resource selector in /v1/businesses/{businessId}/… (ADR-006).
UUIDv7-compatible opaque identifier. {businessId} is not authorization
proof. The resource server must independently verify an active
application-to-business grant, required permission, and ownership (ADR-016,
ADR-022).
UUID with version nibble 7 (UUIDv7). STD-API-01 prefers UUIDv7 for new
platform-generated external resource identifiers. Clients must still treat
the value as opaque. Not every path parameter is guaranteed to be v7 solely
because it is a UUID; use this schema where the contract asserts UUIDv7.
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"018f3c4e-7b2a-7c3d-8e9f-0123456789ab"
Webhook endpoint identifier (UUIDv7).
UUID with version nibble 7 (UUIDv7). STD-API-01 prefers UUIDv7 for new
platform-generated external resource identifiers. Clients must still treat
the value as opaque. Not every path parameter is guaranteed to be v7 solely
because it is a UUID; use this schema where the contract asserts UUIDv7.
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"018f3c4e-7b2a-7c3d-8e9f-0123456789ab"
Body
Partial update (DEC-WH-U01 / DEC-WH-V01). Changing url requires destination
security validation (HTTPS, TLS, SSRF controls) but not ownership
reverification. Updating description, event_types, or status does not
require ownership verification.
HTTPS destination URL (ADR-021 WH-05 / ADR-017 SECOP-09). Backend enforces SSRF controls at connection time (no loopback, link-local, private/internal ranges, unsafe redirects, DNS rebinding). Client-side pattern checks are not sufficient.
12 - 2048^https://"https://hooks.example.com/1funnel/webhooks"
2561Approved v1 outbound event types (ADR-021 WH-02). Wallet and payment events are deferred. Do not rename these values.
sms.message.sent.v1, sms.message.delivered.v1, sms.message.failed.v1, sms.bulk-message.processing.v1, sms.bulk-message.completed.v1, sms.bulk-message.failed.v1, otp.challenge.verified.v1, otp.challenge.expired.v1, otp.challenge.locked.v1 Clients may set active or disabled when eligible.
active, disabled Response
Updated endpoint
Webhook endpoint resource. Never includes signing secrets on read (DEC-WH-R01). Ownership verification is deferred in v1 (DEC-WH-V01).
UUID with version nibble 7 (UUIDv7). STD-API-01 prefers UUIDv7 for new
platform-generated external resource identifiers. Clients must still treat
the value as opaque. Not every path parameter is guaranteed to be v7 solely
because it is a UUID; use this schema where the contract asserts UUIDv7.
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"018f3c4e-7b2a-7c3d-8e9f-0123456789ab"
UUID with version nibble 7 (UUIDv7). STD-API-01 prefers UUIDv7 for new
platform-generated external resource identifiers. Clients must still treat
the value as opaque. Not every path parameter is guaranteed to be v7 solely
because it is a UUID; use this schema where the contract asserts UUIDv7.
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"018f3c4e-7b2a-7c3d-8e9f-0123456789ab"
HTTPS destination URL (ADR-021 WH-05 / ADR-017 SECOP-09). Backend enforces SSRF controls at connection time (no loopback, link-local, private/internal ranges, unsafe redirects, DNS rebinding). Client-side pattern checks are not sufficient.
12 - 2048^https://"https://hooks.example.com/1funnel/webhooks"
Endpoint lifecycle in v1 (DEC-WH-V01 deferred ownership verification;
DEC-WH-E01 soft-delete). Endpoints become active after successful creation
and destination security validation. disabled is the deactivated state
after DELETE or explicit disable. Ownership verification is a future
capability — not a v1 prerequisite.
active, disabled "active"
Approved v1 outbound event types (ADR-021 WH-02). Wallet and payment events are deferred. Do not rename these values.
sms.message.sent.v1, sms.message.delivered.v1, sms.message.failed.v1, sms.bulk-message.processing.v1, sms.bulk-message.completed.v1, sms.bulk-message.failed.v1, otp.challenge.verified.v1, otp.challenge.expired.v1, otp.challenge.locked.v1 RFC 3339 date-time. Response timestamps are UTC with a Z offset
(STD-API-01 D06). Client-supplied timestamps must include an explicit offset;
local times without an offset are rejected.
"2026-10-13T09:00:00.000Z"
RFC 3339 date-time. Response timestamps are UTC with a Z offset
(STD-API-01 D06). Client-supplied timestamps must include an explicit offset;
local times without an offset are rejected.
"2026-10-13T09:00:00.000Z"