CodexPluginStats
← Files YCloud Developer KitARCHIVED FILE

skills/ycloud-webhook-endpoints/references/openapi.md

20.5 KB · Oct 3, 2026 · 06:33 UTC

↓ Download file

<!-- Generated by scripts/build_openapi_skill_references.py; do not edit. -->
# OpenAPI contract: Webhook endpoints

## Provenance

- Source: `ycloud-api-v2.yaml` (pinned release snapshot).
- Source SHA-256: `8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81`
- OpenAPI version: `3.0.0`
- API info.version: `v2`
- This derived reference does not replace the upstream API Owner's canonical source.
- Generated deterministically from normalized JSON; do not edit this file by hand.

## Scope and handoff

- These six operations manage endpoint resources only. They do not define event payload consumption or signature verification. Delete and secret rotation are high-risk plan/confirmation paths and are never executed.
- Operation coverage: `6`

## Operations

### `POST /webhookEndpoints` — `webhook_endpoint-create`

- Summary: Create a webhook endpoint
- Description:
  > Creates a webhook endpoint listening for specific events.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/WebhookEndpointCreateRequest`
    - `$ref`: `#/components/schemas/WebhookEndpointCreateRequest`
- Responses:
  - `200`: Successfully created a webhook endpoint.
    - `application/json`: `#/components/schemas/WebhookEndpoint`
      - `$ref`: `#/components/schemas/WebhookEndpoint`

### `GET /webhookEndpoints` — `webhook_endpoint-list`

- Summary: List webhook endpoints
- Description:
  > Returns a paginated list of webhook endpoints.
- Parameters:
  - `page` (query, optional): `integer (int32)`
    > Page number of the results to be returned, 1-based.
    - Constraints: minimum=1; maximum=100; default=1
  - `limit` (query, optional): `integer (int32)`
    > A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
    - Constraints: minimum=1; maximum=100; default=10
  - `includeTotal` (query, optional): `boolean`
    > Return results inside an object that contains the total result count or not.
    - Constraints: default=false
- Request body: none
- Responses:
  - `200`: Successfully retrieved a paginated list of objects.
    - `application/json`: `#/components/schemas/WebhookEndpointPage`
      - `$ref`: `#/components/schemas/WebhookEndpointPage`

### `GET /webhookEndpoints/{id}` — `webhook_endpoint-retrieve`

- Summary: Retrieve a webhook endpoint
- Description:
  > Retrieves the webhook endpoint with the given ID.
- Parameters:
  - `id` (path, required): `string`
    > ID of the webhook endpoint.
    - Constraints: example="wh627c8640675de8fc689ab9d9"
- Request body: none
- Responses:
  - `200`: Successfully retrieved the webhook endpoint.
    - `application/json`: `#/components/schemas/WebhookEndpoint`
      - `$ref`: `#/components/schemas/WebhookEndpoint`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `PATCH /webhookEndpoints/{id}` — `webhook_endpoint-update`

- Summary: Update a webhook endpoint
- Description:
  > Updates a webhook endpoint, such as url, events, status.
- Parameters:
  - `id` (path, required): `string`
    > ID of the webhook endpoint.
    - Constraints: example="wh627c8640675de8fc689ab9d9"
- Request body: required
  - `application/json`: `#/components/schemas/WebhookEndpointUpdateRequest`
    - `$ref`: `#/components/schemas/WebhookEndpointUpdateRequest`
- Responses:
  - `200`: Successfully updated the webhook endpoint.
    - `application/json`: `#/components/schemas/WebhookEndpoint`
      - `$ref`: `#/components/schemas/WebhookEndpoint`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `DELETE /webhookEndpoints/{id}` — `webhook_endpoint-delete`

- Summary: Delete a webhook endpoint
- Description:
  > Deletes a webhook endpoint.
- Parameters:
  - `id` (path, required): `string`
    > ID of the webhook endpoint.
    - Constraints: example="wh627c8640675de8fc689ab9d9"
- Request body: none
- Responses:
  - `200`: Successfully deleted the webhook endpoint.
    - `application/json`: `#/components/schemas/WebhookEndpoint`
      - `$ref`: `#/components/schemas/WebhookEndpoint`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `POST /webhookEndpoints/{id}/rotateSecret` — `webhook_endpoint-rotate-secret`

- Summary: Rotate a webhook endpoint secret
- Description:
  > Generates a new secret for a webhook endpoint.
- Parameters:
  - `id` (path, required): `string`
    > ID of the webhook endpoint.
    - Constraints: example="wh627c8640675de8fc689ab9d9"
- Request body: none
- Responses:
  - `200`: Successfully rotated the webhook endpoint secret.
    - `application/json`: `#/components/schemas/WebhookEndpoint`
      - `$ref`: `#/components/schemas/WebhookEndpoint`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

## Referenced schema and parameter shapes

### `id-in_path_for_webhook_endpoint`

- Reference: `#/components/parameters/id-in_path_for_webhook_endpoint`
- Parameter name: `id`
- Location: `path`
- Required: `true`
- Description:
  > ID of the webhook endpoint.
- Schema: `string`
  - Constraints: example="wh627c8640675de8fc689ab9d9"

### `includeTotal`

- Reference: `#/components/parameters/includeTotal`
- Parameter name: `includeTotal`
- Location: `query`
- Required: `false`
- Description:
  > Return results inside an object that contains the total result count or not.
- Schema: `boolean`
  - Constraints: default=false

### `limit`

- Reference: `#/components/parameters/limit`
- Parameter name: `limit`
- Location: `query`
- Required: `false`
- Description:
  > A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
- Schema: `integer (int32)`
  - Constraints: minimum=1; maximum=100; default=10

### `page`

- Reference: `#/components/parameters/page`
- Parameter name: `page`
- Location: `query`
- Required: `false`
- Description:
  > Page number of the results to be returned, 1-based.
- Schema: `integer (int32)`
  - Constraints: minimum=1; maximum=100; default=1

### `Error`

- Reference: `#/components/schemas/Error`
- Shape: `object`
  - Required properties: `status`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > One of a server-defined error codes. Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.
      - Constraints: example="NOT_FOUND"
    - `docUrl`: `string`
      - Description:
        > A URL to more information about the error.
      - Constraints: example=""
    - `message`: `string`
      - Description:
        > A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
      - Constraints: example="The requested resource does not exist."
    - `requestId`: `string`
      - Description:
        > Each API request has an associated request ID. It conveys the response header `YCloud-Request-ID` used for the convenience of the consumer.
      - Constraints: example="req_1KjtKI80IKoaJNa6n6p"
    - `status`: `integer (int32)` (required)
      - Description:
        > HTTP status code, [RFC 7231, Section 6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It conveys the HTTP status code used for the convenience of the consumer.
      - Constraints: pattern="[45]\\d{2}"; example=404
    - `target`: `string`
      - Description:
        > The target of the error.
      - Constraints: example=""
    - `whatsappApiError`: `#/components/schemas/WhatsappApiError`
      - Description:
        > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
        >
        > Note: This field is returned if we tried to request the WhatsApp Business API and got an error response.

### `ErrorResponse`

- Reference: `#/components/schemas/ErrorResponse`
- Shape: `object`
  - Required properties: `error`
  - Properties:
    - `error`: `#/components/schemas/Error` (required)

### `EventProperty`

- Reference: `#/components/schemas/EventProperty`
- Shape: `object`
  - Description:
    > Represents event property configuration for webhook endpoints.
    > Specifies which properties should be included in the webhook payload for a specific event type.
  - Required properties: `event`, `properties`
  - Properties:
    - `event`: `string` (required)
      - Description:
        > The event type for which properties are configured.
        > This field accepts any valid event type that supports property configuration.
      - Constraints: example="contact.attributes_changed"
    - `properties`: `array` (required)
      - Description:
        > A list of property names that should be included in the webhook payload for the specified event type.
        > The available properties depend on the specific event type configured.
      - Constraints: minItems=1; example=["attr1", "attr2"]
      - Items: `string`

### `EventType`

- Reference: `#/components/schemas/EventType`
- Shape: `string`
  - Description:
    > Type of event.
  - Constraints: enum=["email.delivery.updated", "sms.message.updated", "sms.inbound.received", "voice.message.updated", "whatsapp.business_account.deleted", "whatsapp.business_account.reviewed", "whatsapp.business_account.updated", "whatsapp.inbound_message.received", "whatsapp.message.updated", "whatsapp.group.lifecycle_update", "whatsapp.group.participants_update", "whatsapp.group.settings_update", "whatsapp.group.status_update", "whatsapp.smb.history", "whatsapp.smb.message.echoes", "whatsapp.phone_number.deleted", "whatsapp.phone_number.name_updated", "whatsapp.phone_number.quality_updated", "whatsapp.phone_number.business_username_updated", "whatsapp.template.category_updated", "whatsapp.template.quality_updated", "whatsapp.template.reviewed", "whatsapp.call.connect", "whatsapp.call.terminate", "whatsapp.call.status.updated", "whatsapp.call.recording.updated", "whatsapp.call.transcription.updated", "whatsapp.flow.status_change", "whatsapp.payment.updated", "contact.attributes_changed", "contact.created", "contact.deleted", "contact.note.created", "contact.note.updated", "contact.note.deleted", "contact.unsubscribe.created", "contact.unsubscribe.deleted", "whatsapp.user.preferences"]

### `Page`

- Reference: `#/components/schemas/Page`
- Shape: `object`
  - Description:
    > Represents a given page of items.
  - Required properties: `offset`, `limit`, `length`
  - Properties:
    - `items`: `array`
      - Items: `object`
    - `length`: `integer (int32)` (required)
      - Description:
        > The actual number of items in the page.
      - Constraints: minimum=0
    - `limit`: `integer (int32)` (required)
      - Description:
        > A limit on the number of items to be returned, between 1 and 100, defaults to 10.
      - Constraints: minimum=1
    - `offset`: `integer (int32)` (required)
      - Description:
        > The position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10.
      - Constraints: minimum=0
    - `total`: `integer (int32)`
      - Description:
        > The total number of items. This field is returned only when the request parameter `includeTotal` is set to `true`.
      - Constraints: minimum=0

### `WebhookEndpoint`

- Reference: `#/components/schemas/WebhookEndpoint`
- Shape: `object`
  - Required properties: `id`
  - Properties:
    - `createTime`: `string (date-time)`
      - Description:
        > The time at which this object was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
      - Constraints: example="2022-06-01T12:00:00.000Z"
    - `description`: `string`
      - Description:
        > An optional description of what the webhook is used for.
      - Constraints: example="My first webhook endpoint."
    - `enabledEvents`: `array`
      - Description:
        > The list of events to enable for this endpoint.
      - Constraints: example=["whatsapp.message.updated", "whatsapp.inbound_message.received"]
      - Items: `string`
    - `eventProperties`: `array`
      - Description:
        > Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types.
        > When `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type.
      - Constraints: example=[{"event": "contact.attributes_changed", "properties": ["attr1", "attr2"]}]
      - Items: `#/components/schemas/EventProperty`
    - `id`: `string` (required)
      - Description:
        > Unique ID for the object.
      - Constraints: example="wh627c8640675de8fc689ab9d9"
    - `secret`: `string`
      - Description:
        > The endpoint's secret, used to generate webhook signatures.
      - Constraints: example="whsec_abc4147651944f02baf3be1eb45d33f1"
    - `status`: `#/components/schemas/WebhookEndpointStatus`
    - `updateTime`: `string (date-time)`
      - Description:
        > The time at which this object was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
      - Constraints: example="2022-06-01T12:00:00.000Z"
    - `url`: `string`
      - Description:
        > The URL of the webhook endpoint.
      - Constraints: example="https://httpbin.org/anything?tag=api"

### `WebhookEndpointCreateRequest`

- Reference: `#/components/schemas/WebhookEndpointCreateRequest`
- Shape: `object`
  - Required properties: `url`, `enabledEvents`
  - Properties:
    - `description`: `string`
      - Description:
        > An optional description of what the webhook is used for.
      - Constraints: maxLength=400; example="My first webhook endpoint."
    - `enabledEvents`: `array` (required)
      - Description:
        > The list of events to enable for this endpoint.
      - Items: `#/components/schemas/EventType`
    - `eventProperties`: `array`
      - Description:
        > Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types.
        > When `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type.
      - Constraints: example=[{"event": "contact.attributes_changed", "properties": ["attr1", "attr2"]}]
      - Items: `#/components/schemas/EventProperty`
    - `status`: `#/components/schemas/WebhookEndpointStatus`
    - `url`: `string` (required)
      - Description:
        > The URL of the webhook endpoint.
      - Constraints: maxLength=500; example="https://httpbin.org/anything?tag=api"

### `WebhookEndpointPage`

- Reference: `#/components/schemas/WebhookEndpointPage`
- Shape: `object`
  - Description:
    > Represents a given page of webhook endpoints.
  - `allOf` composition (preserved; not inferred SDK inheritance):
    - `#/components/schemas/Page`
      - `$ref`: `#/components/schemas/Page`
  - Properties:
    - `items`: `array`
      - Description:
        > An array containing webhook endpoint objects.
      - Items: `#/components/schemas/WebhookEndpoint`
  - Effective wire object after merging `allOf` (use this shape in response adapters):
    - Required properties: `offset`, `limit`, `length`
    - Properties:
      - `items`: `array`
        - Items: `#/components/schemas/WebhookEndpoint`
      - `length`: `integer (int32)` (required)
      - `limit`: `integer (int32)` (required)
      - `offset`: `integer (int32)` (required)
      - `total`: `integer (int32)`

### `WebhookEndpointStatus`

- Reference: `#/components/schemas/WebhookEndpointStatus`
- Shape: `string`
  - Description:
    > Webhook endpoint status.
    > - `active`: Indicates that the webhook endpoint is active, and will receive notifications of events monitored.
    > - `disabled`: Indicates that the webhook endpoint is disabled, and will not receive notifications.
    > - `pending`: Indicates that the webhook endpoint is pending, and will not receive notifications. If a webhook endpoint fails to receive notifications frequently, it changes to pending.
  - Constraints: enum=["active", "disabled", "pending"]

### `WebhookEndpointUpdateRequest`

- Reference: `#/components/schemas/WebhookEndpointUpdateRequest`
- Shape: `object`
  - Properties:
    - `description`: `string`
      - Description:
        > An optional description of what the webhook is used for.
      - Constraints: maxLength=400; example="My first webhook endpoint."
    - `enabledEvents`: `array`
      - Description:
        > The list of events to enable for this endpoint.
      - Items: `#/components/schemas/EventType`
    - `eventProperties`: `array`
      - Description:
        > Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types.
        > When `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type.
      - Constraints: example=[{"event": "contact.attributes_changed", "properties": ["attr1", "attr2"]}]
      - Items: `#/components/schemas/EventProperty`
    - `status`: `#/components/schemas/WebhookEndpointStatus`
    - `url`: `string`
      - Description:
        > The URL of the webhook endpoint.
      - Constraints: maxLength=500; example="https://httpbin.org/anything?tag=api"

### `WhatsappApiError`

- Reference: `#/components/schemas/WhatsappApiError`
- Shape: `object`
  - Description:
    > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
  - Required properties: `message`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > An error code.
      - Constraints: example=200002
    - `error_data`: `object`
      - Description:
        > Additional data about the error. A string or map.
        > - For template APIs, this field is a string describing the reason for the error.
        > - For message APIs, this field is a map with property `details` describing the reason for the error.
    - `error_subcode`: `string`
      - Description:
        > Additional code about the error.
      - Constraints: example=2388109
    - `error_user_msg`: `string`
      - Description:
        > The message to display to the user. The language of the message is based on the locale of the API request.
      - Constraints: example="This message template cannot be created."
    - `error_user_title`: `string`
      - Description:
        > The title of the dialog, if shown. The language of the message is based on the locale of the API request.
      - Constraints: example="Message Cannot Be Submitted"
    - `fbtrace_id`: `string`
      - Description:
        > Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging.
      - Constraints: example="AVGjJ7ia2zJkrHG"
    - `is_transient`: `boolean`
      - Description:
        > Whether the error is transient.
      - Constraints: example=false
    - `message`: `string` (required)
      - Description:
        > A human-readable description of the error.
      - Constraints: example="HSM Template creation failed"
    - `type`: `string`
      - Description:
        > Error type.
      - Constraints: example="OAuthException"

## Codegen interpretation and unknowns

- `operationId` identifies the OpenAPI operation; it is not an SDK method name.
- `allOf` is wire-level schema composition. Response adapters must merge inherited and local properties; generated model inheritance/flattening is only a codegen shape, not additional API behavior.
- `x-group-parameters`, `x-enum-varnames`, and `x-enum-descriptions` are generator hints, not business rules.
- Description-only constraints (including conditional fields, precedence, and endpoint-specific behavior) remain verbatim above.
- This OpenAPI snapshot does not confirm cross-cutting error, retry/`Retry-After`, rate-limit, idempotency, delivery, or webhook-signature behavior. Consult the reviewed `runtime.md`; if neither source confirms a fact, do not fill it in.

SHA-256: 0536c48552dcba8883754b44dc791d81835c01470795175f3ed0f2e8931ca3db