# Webhook endpoints

## Endpoints

- `POST /messaging/webhooks`: [Create webhook](https://docs.polymorfa.com/api/webhook-endpoints/create-webhook) (Messaging API)
- `POST /platform/webhooks`: [Create team webhook](https://docs.polymorfa.com/api/webhook-endpoints/create-team-webhook) (Platform API)
- `POST /platform/projects/{projectId}/webhooks`: [Create project webhook](https://docs.polymorfa.com/api/webhook-endpoints/create-project-webhook) (Platform API)
- `GET /messaging/webhooks`: [List webhooks](https://docs.polymorfa.com/api/webhook-endpoints/list-webhooks) (Messaging API)
- `GET /platform/webhooks`: [List team webhooks](https://docs.polymorfa.com/api/webhook-endpoints/list-team-webhooks) (Platform API)
- `GET /platform/projects/{projectId}/webhooks`: [List project webhooks](https://docs.polymorfa.com/api/webhook-endpoints/list-project-webhooks) (Platform API)
- `GET /messaging/webhooks/{id}`: [Get webhook](https://docs.polymorfa.com/api/webhook-endpoints/get-webhook) (Messaging API)
- `GET /platform/webhooks/{webhookId}`: [Get team webhook](https://docs.polymorfa.com/api/webhook-endpoints/get-team-webhook) (Platform API)
- `GET /platform/projects/{projectId}/webhooks/{webhookId}`: [Get project webhook](https://docs.polymorfa.com/api/webhook-endpoints/get-project-webhook) (Platform API)
- `PUT /messaging/webhooks/{id}`: [Update webhook](https://docs.polymorfa.com/api/webhook-endpoints/update-webhook) (Messaging API)
- `PATCH /platform/webhooks/{webhookId}`: [Update team webhook](https://docs.polymorfa.com/api/webhook-endpoints/update-team-webhook) (Platform API)
- `PATCH /platform/projects/{projectId}/webhooks/{webhookId}`: [Update project webhook](https://docs.polymorfa.com/api/webhook-endpoints/update-project-webhook) (Platform API)
- `POST /platform/webhooks/{webhookId}/secret-rotations`: [Rotate team webhook secret](https://docs.polymorfa.com/api/webhook-endpoints/rotate-team-webhook-secret) (Platform API)
- `POST /platform/webhooks/{webhookId}/tests`: [Test team webhook](https://docs.polymorfa.com/api/webhook-endpoints/test-team-webhook) (Platform API)
- `POST /platform/projects/{projectId}/webhooks/{webhookId}/secret-rotations`: [Rotate project webhook secret](https://docs.polymorfa.com/api/webhook-endpoints/rotate-project-webhook-secret) (Platform API)
- `POST /platform/projects/{projectId}/webhooks/{webhookId}/tests`: [Test project webhook](https://docs.polymorfa.com/api/webhook-endpoints/test-project-webhook) (Platform API)
- `DELETE /messaging/webhooks/{id}`: [Delete webhook](https://docs.polymorfa.com/api/webhook-endpoints/delete-webhook) (Messaging API)
- `DELETE /platform/webhooks/{webhookId}`: [Delete team webhook](https://docs.polymorfa.com/api/webhook-endpoints/delete-team-webhook) (Platform API)
- `DELETE /platform/projects/{projectId}/webhooks/{webhookId}`: [Delete project webhook](https://docs.polymorfa.com/api/webhook-endpoints/delete-project-webhook) (Platform API)

## The team webhook object

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `teamId` (string (uuid), required, format uuid). Identifier for the team.
- `owner` (string, required). Specifies owner for this management team webhook. Values: `team`.
- `projectId` (string, required, nullable). Identifier of the Polymorfa project that owns this resource.
- `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
- `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management team webhook.
- `enabled` (boolean, required). Whether this feature is enabled.
- `format` (string, required). Specifies format for this management team webhook. Values: `native`, `meta`.
- `retryPolicy` (object, required). Specifies retry policy for this management team webhook.
  - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
  - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
  - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
- `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
- `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
  - `name` (string, required, length 1–128). Human-readable name for this resource.
- `secret` (object, required). Specifies secret for this management team webhook.
  - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
- `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
- `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "teamId": "00000000-0000-4000-8000-000000000000",
  "owner": "team",
  "projectId": null,
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "enabled": true,
  "format": "native",
  "retryPolicy": {
    "maximumAttempts": 1,
    "backoff": "constant",
    "initialDelaySeconds": 1
  },
  "phoneOfflineStartDay": 7,
  "headers": [
    {
      "name": "string"
    }
  ],
  "secret": {
    "version": 1,
    "createdAt": "2026-09-22T12:00:00Z",
    "previousValidUntil": "2026-09-22T12:00:00Z"
  },
  "createdAt": "2026-09-22T12:00:00Z",
  "updatedAt": "2026-09-22T12:00:00Z"
}
```

## The project webhook object

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `teamId` (string (uuid), required, format uuid). Identifier for the team.
- `owner` (string, required). Specifies owner for this management project webhook. Values: `project`.
- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
- `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management project webhook.
- `enabled` (boolean, required). Whether this feature is enabled.
- `format` (string, required). Specifies format for this management project webhook. Values: `native`, `meta`.
- `retryPolicy` (object, required). Specifies retry policy for this management project webhook.
  - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
  - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
  - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
- `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
- `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
  - `name` (string, required, length 1–128). Human-readable name for this resource.
- `secret` (object, required). Specifies secret for this management project webhook.
  - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
- `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
- `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "teamId": "00000000-0000-4000-8000-000000000000",
  "owner": "project",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "enabled": true,
  "format": "native",
  "retryPolicy": {
    "maximumAttempts": 1,
    "backoff": "constant",
    "initialDelaySeconds": 1
  },
  "phoneOfflineStartDay": 7,
  "headers": [
    {
      "name": "string"
    }
  ],
  "secret": {
    "version": 1,
    "createdAt": "2026-09-22T12:00:00Z",
    "previousValidUntil": "2026-09-22T12:00:00Z"
  },
  "createdAt": "2026-09-22T12:00:00Z",
  "updatedAt": "2026-09-22T12:00:00Z"
}
```

## The Messaging API webhook object

### Attributes

- `id` (string, required). Identifier for this resource.
- `tenantId` (string, required). Identifier of the team that owns this resource.
- `session` (string). Identifier of the connected Polymorfa session.
- `url` (string, required). URL associated with this resource.
- `events` (array of string, required). Events returned or subscribed to by this operation.
- `retries` (object, required). Retry policy applied after a failed delivery attempt.
  - `attempts` (integer, required, min 0). Specifies attempts for this native retry config.
  - `delaySeconds` (integer, required, min 0). Specifies delay seconds for this native retry config.
  - `policy` (string, required). linear, exponential, or constant
- `headers` (array of object, required). HTTP headers attached to the outgoing request.
  - `name` (string, required). Human-readable name for this resource.
  - `value` (string, required). Value assigned to this field.
- `enabled` (boolean, required). Whether this feature is enabled.
- `format` (string). Specifies format for this native webhook. Values: `native`, `meta`.
- `phoneOfflineStartDay` (integer, range 7–13). Specifies phone offline start day for this native webhook.
- `createdAt` (string, required). ISO 8601 timestamp when this resource was created.
```json
{
  "id": "string",
  "tenantId": "string",
  "session": "string",
  "url": "string",
  "events": [
    "string"
  ],
  "retries": {
    "attempts": 0,
    "delaySeconds": 0,
    "policy": "string"
  },
  "headers": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "enabled": true,
  "format": "native",
  "phoneOfflineStartDay": 7,
  "createdAt": "string"
}
```

## Create webhook

`POST https://api.polymorfa.com/messaging/webhooks` (Messaging API)

Required permission: `webhooks:manage`

**Required scope:** `webhooks:manage`

### Body

- `session` (string). Identifier of the connected Polymorfa session.
- `url` (string (uri), required, format uri). URL associated with this resource.
- `events` (array of string, max items 1000). Event types this webhook subscribes to.
- `hmacKey` (string). HMAC key used to verify signed payloads.
- `retries` (object). Retry policy applied after a failed delivery attempt.
  - `attempts` (integer, required, min 0). Specifies attempts for this native retry config.
  - `delaySeconds` (integer, required, min 0). Specifies delay seconds for this native retry config.
  - `policy` (string, required). linear, exponential, or constant
- `headers` (array of object, max items 1000). HTTP headers attached to the outgoing request.
  - `name` (string, required). Human-readable name for this resource.
  - `value` (string, required). Value assigned to this field.
- `format` (string). "native" (default) = Polymorfa event envelope. "meta" = Meta Cloud API webhook shape (object/entry/changes/value), signed with X-Hub-Signature-256. Values: `native`, `meta`.
- `phoneOfflineStartDay` (integer, range 7–13). First day without the phone on which this webhook receives session.phone_offline. New webhooks default to 10; on update, omission keeps the stored value. WhatsApp signs the linked device out on day 14. To stop the warning, remove session.phone_offline from events.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/webhooks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com"
}'
```

### Responses

#### 201

Webhook created
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `tenantId` (string, required). Identifier of the team that owns this resource.
  - `session` (string). Identifier of the connected Polymorfa session.
  - `url` (string, required). URL associated with this resource.
  - `events` (array of string, required). Events returned or subscribed to by this operation.
  - `retries` (object, required). Retry policy applied after a failed delivery attempt.
    - `attempts` (integer, required, min 0). Specifies attempts for this native retry config.
    - `delaySeconds` (integer, required, min 0). Specifies delay seconds for this native retry config.
    - `policy` (string, required). linear, exponential, or constant
  - `headers` (array of object, required). HTTP headers attached to the outgoing request.
    - `name` (string, required). Human-readable name for this resource.
    - `value` (string, required). Value assigned to this field.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string). Specifies format for this native webhook. Values: `native`, `meta`.
  - `phoneOfflineStartDay` (integer, range 7–13). Specifies phone offline start day for this native webhook.
  - `createdAt` (string, required). ISO 8601 timestamp when this resource was created.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "string",
    "tenantId": "string",
    "url": "string",
    "events": [
      "string"
    ],
    "retries": {
      "attempts": 0,
      "delaySeconds": 0,
      "policy": "string"
    },
    "headers": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "enabled": true,
    "createdAt": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Create team webhook

`POST https://api.polymorfa.com/platform/webhooks` (Platform API)

Required permission: `webhooks:manage`

Creates a team-owned webhook and returns its generated signing secret once.

Team keys require `webhooks:manage`. Project tokens are not accepted.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `url` (string (uri), required, length 1–2048, format uri). URL associated with this resource.
- `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
- `enabled` (boolean). Whether this feature is enabled. Default: `true`.
- `format` (string). Specifies format for this management create team webhook input. Values: `native`, `meta`. Default: `"native"`.
- `retryPolicy` (object). Specifies retry policy for this management create team webhook input.
  - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy input.
  - `backoff` (string, required). Specifies backoff for this management webhook retry policy input. Values: `constant`, `linear`, `exponential`.
  - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy input.
- `phoneOfflineStartDay` (integer, range 7–13). First day without the phone on which this endpoint receives session.phone_offline. WhatsApp signs the linked device out on day 14. On PATCH, omission preserves the stored value. To stop the warning, remove session.phone_offline from eventTypes. Default: `10`.
- `headers` (array of object, max items 10). HTTP headers attached to the outgoing request.
  - `name` (string, required, length 1–128, pattern ^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$). Human-readable name for this resource.
  - `value` (string, required, max length 4096, UTF-8 size: At most `4096` UTF-8 bytes, pattern ^(?![\s\S]*[\u0000-\u0008\u000A-\u001F\u007F])[\s\S]*$). Encrypted write-only HTTP field value. Limited to 4096 UTF-8 bytes. Line breaks, NUL, and other control characters except horizontal tab are rejected.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/webhooks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ]
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhook` (object, required). Specifies webhook for this management team webhook creation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `teamId` (string (uuid), required, format uuid). Identifier for the team.
    - `owner` (string, required). Specifies owner for this management team webhook. Values: `team`.
    - `projectId` (string, required, nullable). Identifier of the Polymorfa project that owns this resource.
    - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
    - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management team webhook.
    - `enabled` (boolean, required). Whether this feature is enabled.
    - `format` (string, required). Specifies format for this management team webhook. Values: `native`, `meta`.
    - `retryPolicy` (object, required). Specifies retry policy for this management team webhook.
      - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
      - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
      - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
    - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
    - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
      - `name` (string, required, length 1–128). Human-readable name for this resource.
    - `secret` (object, required). Specifies secret for this management team webhook.
      - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
      - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
      - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management team webhook creation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.
  - `secret` (string, required, nullable). Specifies secret for this management team webhook creation receipt.
  - `secretAvailable` (boolean, required). Whether secret available.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhook": {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "owner": "team",
      "projectId": null,
      "url": "https://example.com",
      "eventTypes": [
        "string"
      ],
      "enabled": true,
      "format": "native",
      "retryPolicy": {
        "maximumAttempts": 1,
        "backoff": "constant",
        "initialDelaySeconds": 1
      },
      "phoneOfflineStartDay": 7,
      "headers": [
        {
          "name": "string"
        }
      ],
      "secret": {
        "version": 1,
        "createdAt": "2026-09-22T12:00:00Z",
        "previousValidUntil": "2026-09-22T12:00:00Z"
      },
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    },
    "operationId": null,
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "secret": "string",
    "secretAvailable": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Create project webhook

`POST https://api.polymorfa.com/platform/projects/{projectId}/webhooks` (Platform API)

Required permission: `webhooks:manage`

Creates a project-owned webhook and returns its generated signing secret once.

Requires `webhooks:manage`. Project tokens only access resources in their own project.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `url` (string (uri), required, length 1–2048, format uri). URL associated with this resource.
- `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
- `enabled` (boolean). Whether this feature is enabled. Default: `true`.
- `format` (string). Specifies format for this management create project webhook input. Values: `native`, `meta`. Default: `"native"`.
- `retryPolicy` (object). Specifies retry policy for this management create project webhook input.
  - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy input.
  - `backoff` (string, required). Specifies backoff for this management webhook retry policy input. Values: `constant`, `linear`, `exponential`.
  - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy input.
- `phoneOfflineStartDay` (integer, range 7–13). First day without the phone on which this endpoint receives session.phone_offline. WhatsApp signs the linked device out on day 14. On PATCH, omission preserves the stored value. To stop the warning, remove session.phone_offline from eventTypes. Default: `10`.
- `headers` (array of object, max items 10). HTTP headers attached to the outgoing request.
  - `name` (string, required, length 1–128, pattern ^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$). Human-readable name for this resource.
  - `value` (string, required, max length 4096, UTF-8 size: At most `4096` UTF-8 bytes, pattern ^(?![\s\S]*[\u0000-\u0008\u000A-\u001F\u007F])[\s\S]*$). Encrypted write-only HTTP field value. Limited to 4096 UTF-8 bytes. Line breaks, NUL, and other control characters except horizontal tab are rejected.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/webhooks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ]
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhook` (object, required). Specifies webhook for this management project webhook creation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `teamId` (string (uuid), required, format uuid). Identifier for the team.
    - `owner` (string, required). Specifies owner for this management project webhook. Values: `project`.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
    - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management project webhook.
    - `enabled` (boolean, required). Whether this feature is enabled.
    - `format` (string, required). Specifies format for this management project webhook. Values: `native`, `meta`.
    - `retryPolicy` (object, required). Specifies retry policy for this management project webhook.
      - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
      - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
      - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
    - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
    - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
      - `name` (string, required, length 1–128). Human-readable name for this resource.
    - `secret` (object, required). Specifies secret for this management project webhook.
      - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
      - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
      - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management project webhook creation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.
  - `secret` (string, required, nullable). Specifies secret for this management project webhook creation receipt.
  - `secretAvailable` (boolean, required). Whether secret available.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhook": {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "owner": "project",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "url": "https://example.com",
      "eventTypes": [
        "string"
      ],
      "enabled": true,
      "format": "native",
      "retryPolicy": {
        "maximumAttempts": 1,
        "backoff": "constant",
        "initialDelaySeconds": 1
      },
      "phoneOfflineStartDay": 7,
      "headers": [
        {
          "name": "string"
        }
      ],
      "secret": {
        "version": 1,
        "createdAt": "2026-09-22T12:00:00Z",
        "previousValidUntil": "2026-09-22T12:00:00Z"
      },
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    },
    "operationId": null,
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "secret": "string",
    "secretAvailable": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## List webhooks

`GET https://api.polymorfa.com/messaging/webhooks` (Messaging API)

Required permission: `webhooks:manage`

**Required scope:** `webhooks:manage`

### Request

```bash
curl "https://api.polymorfa.com/messaging/webhooks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Webhook list
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `tenantId` (string, required). Identifier of the team that owns this resource.
  - `session` (string). Identifier of the connected Polymorfa session.
  - `url` (string, required). URL associated with this resource.
  - `events` (array of string, required). Events returned or subscribed to by this operation.
  - `retries` (object, required). Retry policy applied after a failed delivery attempt.
    - `attempts` (integer, required, min 0). Specifies attempts for this native retry config.
    - `delaySeconds` (integer, required, min 0). Specifies delay seconds for this native retry config.
    - `policy` (string, required). linear, exponential, or constant
  - `headers` (array of object, required). HTTP headers attached to the outgoing request.
    - `name` (string, required). Human-readable name for this resource.
    - `value` (string, required). Value assigned to this field.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string). Specifies format for this native webhook. Values: `native`, `meta`.
  - `phoneOfflineStartDay` (integer, range 7–13). Specifies phone offline start day for this native webhook.
  - `createdAt` (string, required). ISO 8601 timestamp when this resource was created.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": [
    {
      "id": "string",
      "tenantId": "string",
      "url": "string",
      "events": [
        "string"
      ],
      "retries": {
        "attempts": 0,
        "delaySeconds": 0,
        "policy": "string"
      },
      "headers": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "enabled": true,
      "createdAt": "string"
    }
  ]
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## List team webhooks

`GET https://api.polymorfa.com/platform/webhooks` (Platform API)

Required permission: `webhooks:read`

Lists only team-owned webhook endpoints. Project-owned endpoints are excluded.

Team keys require `webhooks:read`. Project tokens are not accepted.

### Query parameters

- `eventType` (string, length 1–128). Category assigned to event.
- `enabled` (boolean). Whether this feature is enabled.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.
- `cursor` (string). Specifies cursor for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/platform/webhooks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `owner` (string, required). Specifies owner for this management team webhook. Values: `team`.
  - `projectId` (string, required, nullable). Identifier of the Polymorfa project that owns this resource.
  - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
  - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management team webhook.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string, required). Specifies format for this management team webhook. Values: `native`, `meta`.
  - `retryPolicy` (object, required). Specifies retry policy for this management team webhook.
    - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
    - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
    - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
  - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
  - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
    - `name` (string, required, length 1–128). Human-readable name for this resource.
  - `secret` (object, required). Specifies secret for this management team webhook.
    - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "owner": "team",
      "projectId": null,
      "url": "https://example.com",
      "eventTypes": [
        "string"
      ],
      "enabled": true,
      "format": "native",
      "retryPolicy": {
        "maximumAttempts": 1,
        "backoff": "constant",
        "initialDelaySeconds": 1
      },
      "phoneOfflineStartDay": 7,
      "headers": [
        {
          "name": "string"
        }
      ],
      "secret": {
        "version": 1,
        "createdAt": "2026-09-22T12:00:00Z",
        "previousValidUntil": "2026-09-22T12:00:00Z"
      },
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## List project webhooks

`GET https://api.polymorfa.com/platform/projects/{projectId}/webhooks` (Platform API)

Required permission: `webhooks:read`

Lists webhooks owned by the exact project in the route.

Requires `webhooks:read`. Project tokens only access resources in their own project.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Query parameters

- `eventType` (string, length 1–128). Category assigned to event.
- `enabled` (boolean). Whether this feature is enabled.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.
- `cursor` (string). Specifies cursor for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/platform/projects/<projectId>/webhooks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `owner` (string, required). Specifies owner for this management project webhook. Values: `project`.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
  - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management project webhook.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string, required). Specifies format for this management project webhook. Values: `native`, `meta`.
  - `retryPolicy` (object, required). Specifies retry policy for this management project webhook.
    - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
    - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
    - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
  - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
  - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
    - `name` (string, required, length 1–128). Human-readable name for this resource.
  - `secret` (object, required). Specifies secret for this management project webhook.
    - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "owner": "project",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "url": "https://example.com",
      "eventTypes": [
        "string"
      ],
      "enabled": true,
      "format": "native",
      "retryPolicy": {
        "maximumAttempts": 1,
        "backoff": "constant",
        "initialDelaySeconds": 1
      },
      "phoneOfflineStartDay": 7,
      "headers": [
        {
          "name": "string"
        }
      ],
      "secret": {
        "version": 1,
        "createdAt": "2026-09-22T12:00:00Z",
        "previousValidUntil": "2026-09-22T12:00:00Z"
      },
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get webhook

`GET https://api.polymorfa.com/messaging/webhooks/{id}` (Messaging API)

Required permission: `webhooks:manage`

**Required scope:** `webhooks:manage`

### Path parameters

- `id` (string, required). Identifier for this resource.

### Request

```bash
curl "https://api.polymorfa.com/messaging/webhooks/<id>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Webhook details
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `tenantId` (string, required). Identifier of the team that owns this resource.
  - `session` (string). Identifier of the connected Polymorfa session.
  - `url` (string, required). URL associated with this resource.
  - `events` (array of string, required). Events returned or subscribed to by this operation.
  - `retries` (object, required). Retry policy applied after a failed delivery attempt.
    - `attempts` (integer, required, min 0). Specifies attempts for this native retry config.
    - `delaySeconds` (integer, required, min 0). Specifies delay seconds for this native retry config.
    - `policy` (string, required). linear, exponential, or constant
  - `headers` (array of object, required). HTTP headers attached to the outgoing request.
    - `name` (string, required). Human-readable name for this resource.
    - `value` (string, required). Value assigned to this field.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string). Specifies format for this native webhook. Values: `native`, `meta`.
  - `phoneOfflineStartDay` (integer, range 7–13). Specifies phone offline start day for this native webhook.
  - `createdAt` (string, required). ISO 8601 timestamp when this resource was created.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "string",
    "tenantId": "string",
    "url": "string",
    "events": [
      "string"
    ],
    "retries": {
      "attempts": 0,
      "delaySeconds": 0,
      "policy": "string"
    },
    "headers": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "enabled": true,
    "createdAt": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Get team webhook

`GET https://api.polymorfa.com/platform/webhooks/{webhookId}` (Platform API)

Required permission: `webhooks:read`

Returns one team-owned webhook without secret values.

Team keys require `webhooks:read`. Project tokens are not accepted.

### Path parameters

- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Request

```bash
curl "https://api.polymorfa.com/platform/webhooks/<webhookId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `owner` (string, required). Specifies owner for this management team webhook. Values: `team`.
  - `projectId` (string, required, nullable). Identifier of the Polymorfa project that owns this resource.
  - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
  - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management team webhook.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string, required). Specifies format for this management team webhook. Values: `native`, `meta`.
  - `retryPolicy` (object, required). Specifies retry policy for this management team webhook.
    - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
    - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
    - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
  - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
  - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
    - `name` (string, required, length 1–128). Human-readable name for this resource.
  - `secret` (object, required). Specifies secret for this management team webhook.
    - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "teamId": "00000000-0000-4000-8000-000000000000",
    "owner": "team",
    "projectId": null,
    "url": "https://example.com",
    "eventTypes": [
      "string"
    ],
    "enabled": true,
    "format": "native",
    "retryPolicy": {
      "maximumAttempts": 1,
      "backoff": "constant",
      "initialDelaySeconds": 1
    },
    "phoneOfflineStartDay": 7,
    "headers": [
      {
        "name": "string"
      }
    ],
    "secret": {
      "version": 1,
      "createdAt": "2026-09-22T12:00:00Z",
      "previousValidUntil": "2026-09-22T12:00:00Z"
    },
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get project webhook

`GET https://api.polymorfa.com/platform/projects/{projectId}/webhooks/{webhookId}` (Platform API)

Required permission: `webhooks:read`

Returns one webhook owned by the exact project without secret values.

Requires `webhooks:read`. Project tokens only access resources in their own project.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Request

```bash
curl "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `owner` (string, required). Specifies owner for this management project webhook. Values: `project`.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
  - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management project webhook.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string, required). Specifies format for this management project webhook. Values: `native`, `meta`.
  - `retryPolicy` (object, required). Specifies retry policy for this management project webhook.
    - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
    - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
    - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
  - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
  - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
    - `name` (string, required, length 1–128). Human-readable name for this resource.
  - `secret` (object, required). Specifies secret for this management project webhook.
    - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "teamId": "00000000-0000-4000-8000-000000000000",
    "owner": "project",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "url": "https://example.com",
    "eventTypes": [
      "string"
    ],
    "enabled": true,
    "format": "native",
    "retryPolicy": {
      "maximumAttempts": 1,
      "backoff": "constant",
      "initialDelaySeconds": 1
    },
    "phoneOfflineStartDay": 7,
    "headers": [
      {
        "name": "string"
      }
    ],
    "secret": {
      "version": 1,
      "createdAt": "2026-09-22T12:00:00Z",
      "previousValidUntil": "2026-09-22T12:00:00Z"
    },
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Update webhook

`PUT https://api.polymorfa.com/messaging/webhooks/{id}` (Messaging API)

Required permission: `webhooks:manage`

**Required scope:** `webhooks:manage`

### Path parameters

- `id` (string, required). Identifier for this resource.

### Body

- `url` (string (uri), format uri). URL associated with this resource.
- `events` (array of string, max items 1000). Event types this webhook subscribes to.
- `hmacKey` (string). HMAC key used to verify signed payloads.
- `retries` (object). Retry policy applied after a failed delivery attempt.
  - `attempts` (integer, required, min 0). Specifies attempts for this native retry config.
  - `delaySeconds` (integer, required, min 0). Specifies delay seconds for this native retry config.
  - `policy` (string, required). linear, exponential, or constant
- `headers` (array of object, max items 1000). HTTP headers attached to the outgoing request.
  - `name` (string, required). Human-readable name for this resource.
  - `value` (string, required). Value assigned to this field.
- `enabled` (boolean). Whether this feature is enabled.
- `format` (string). Specifies format for this native update webhook request. Values: `native`, `meta`.
- `phoneOfflineStartDay` (integer, range 7–13). First day without the phone on which this webhook receives session.phone_offline. New webhooks default to 10; on update, omission keeps the stored value. WhatsApp signs the linked device out on day 14. To stop the warning, remove session.phone_offline from events.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/messaging/webhooks/<id>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "events": [
    "string"
  ],
  "hmacKey": "string",
  "retries": {
    "attempts": 0,
    "delaySeconds": 0,
    "policy": "string"
  },
  "headers": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "enabled": true,
  "format": "native",
  "phoneOfflineStartDay": 7
}'
```

### Responses

#### 200

Webhook updated
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `tenantId` (string, required). Identifier of the team that owns this resource.
  - `session` (string). Identifier of the connected Polymorfa session.
  - `url` (string, required). URL associated with this resource.
  - `events` (array of string, required). Events returned or subscribed to by this operation.
  - `retries` (object, required). Retry policy applied after a failed delivery attempt.
    - `attempts` (integer, required, min 0). Specifies attempts for this native retry config.
    - `delaySeconds` (integer, required, min 0). Specifies delay seconds for this native retry config.
    - `policy` (string, required). linear, exponential, or constant
  - `headers` (array of object, required). HTTP headers attached to the outgoing request.
    - `name` (string, required). Human-readable name for this resource.
    - `value` (string, required). Value assigned to this field.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `format` (string). Specifies format for this native webhook. Values: `native`, `meta`.
  - `phoneOfflineStartDay` (integer, range 7–13). Specifies phone offline start day for this native webhook.
  - `createdAt` (string, required). ISO 8601 timestamp when this resource was created.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "string",
    "tenantId": "string",
    "url": "string",
    "events": [
      "string"
    ],
    "retries": {
      "attempts": 0,
      "delaySeconds": 0,
      "policy": "string"
    },
    "headers": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "enabled": true,
    "createdAt": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Update team webhook

`PATCH https://api.polymorfa.com/platform/webhooks/{webhookId}` (Platform API)

Required permission: `webhooks:manage`

Updates settings without rotating the signing secret.

Team keys require `webhooks:manage`. Project tokens are not accepted.

### Path parameters

- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `url` (string (uri), length 1–2048, format uri). URL associated with this resource.
- `eventTypes` (array of string, items 1–100, unique items, item length 1–128). Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
- `enabled` (boolean). Whether this feature is enabled.
- `format` (string). Specifies format for this management update team webhook input. Values: `native`, `meta`.
- `retryPolicy` (object). Specifies retry policy for this management update team webhook input.
  - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy input.
  - `backoff` (string, required). Specifies backoff for this management webhook retry policy input. Values: `constant`, `linear`, `exponential`.
  - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy input.
- `phoneOfflineStartDay` (integer, range 7–13). First day without the phone on which this endpoint receives session.phone_offline. WhatsApp signs the linked device out on day 14. On PATCH, omission preserves the stored value. To stop the warning, remove session.phone_offline from eventTypes.
- `headers` (array of object, max items 10). HTTP headers attached to the outgoing request.
  - `name` (string, required, length 1–128, pattern ^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$). Human-readable name for this resource.
  - `value` (string, required, max length 4096, UTF-8 size: At most `4096` UTF-8 bytes, pattern ^(?![\s\S]*[\u0000-\u0008\u000A-\u001F\u007F])[\s\S]*$). Encrypted write-only HTTP field value. Limited to 4096 UTF-8 bytes. Line breaks, NUL, and other control characters except horizontal tab are rejected.

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/platform/webhooks/<webhookId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "enabled": true,
  "format": "native",
  "retryPolicy": {
    "maximumAttempts": 1,
    "backoff": "constant",
    "initialDelaySeconds": 1
  },
  "phoneOfflineStartDay": 7,
  "headers": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhook` (object, required). Specifies webhook for this management team webhook mutation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `teamId` (string (uuid), required, format uuid). Identifier for the team.
    - `owner` (string, required). Specifies owner for this management team webhook. Values: `team`.
    - `projectId` (string, required, nullable). Identifier of the Polymorfa project that owns this resource.
    - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
    - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management team webhook.
    - `enabled` (boolean, required). Whether this feature is enabled.
    - `format` (string, required). Specifies format for this management team webhook. Values: `native`, `meta`.
    - `retryPolicy` (object, required). Specifies retry policy for this management team webhook.
      - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
      - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
      - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
    - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
    - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
      - `name` (string, required, length 1–128). Human-readable name for this resource.
    - `secret` (object, required). Specifies secret for this management team webhook.
      - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
      - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
      - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management team webhook mutation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhook": {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "owner": "team",
      "projectId": null,
      "url": "https://example.com",
      "eventTypes": [
        "string"
      ],
      "enabled": true,
      "format": "native",
      "retryPolicy": {
        "maximumAttempts": 1,
        "backoff": "constant",
        "initialDelaySeconds": 1
      },
      "phoneOfflineStartDay": 7,
      "headers": [
        {
          "name": "string"
        }
      ],
      "secret": {
        "version": 1,
        "createdAt": "2026-09-22T12:00:00Z",
        "previousValidUntil": "2026-09-22T12:00:00Z"
      },
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    },
    "operationId": null,
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Update project webhook

`PATCH https://api.polymorfa.com/platform/projects/{projectId}/webhooks/{webhookId}` (Platform API)

Required permission: `webhooks:manage`

Updates settings without rotating the signing secret.

Requires `webhooks:manage`. Project tokens only access resources in their own project.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `url` (string (uri), length 1–2048, format uri). URL associated with this resource.
- `eventTypes` (array of string, items 1–100, unique items, item length 1–128). Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
- `enabled` (boolean). Whether this feature is enabled.
- `format` (string). Specifies format for this management update project webhook input. Values: `native`, `meta`.
- `retryPolicy` (object). Specifies retry policy for this management update project webhook input.
  - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy input.
  - `backoff` (string, required). Specifies backoff for this management webhook retry policy input. Values: `constant`, `linear`, `exponential`.
  - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy input.
- `phoneOfflineStartDay` (integer, range 7–13). First day without the phone on which this endpoint receives session.phone_offline. WhatsApp signs the linked device out on day 14. On PATCH, omission preserves the stored value. To stop the warning, remove session.phone_offline from eventTypes.
- `headers` (array of object, max items 10). HTTP headers attached to the outgoing request.
  - `name` (string, required, length 1–128, pattern ^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$). Human-readable name for this resource.
  - `value` (string, required, max length 4096, UTF-8 size: At most `4096` UTF-8 bytes, pattern ^(?![\s\S]*[\u0000-\u0008\u000A-\u001F\u007F])[\s\S]*$). Encrypted write-only HTTP field value. Limited to 4096 UTF-8 bytes. Line breaks, NUL, and other control characters except horizontal tab are rejected.

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "enabled": true,
  "format": "native",
  "retryPolicy": {
    "maximumAttempts": 1,
    "backoff": "constant",
    "initialDelaySeconds": 1
  },
  "phoneOfflineStartDay": 7,
  "headers": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhook` (object, required). Specifies webhook for this management project webhook mutation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `teamId` (string (uuid), required, format uuid). Identifier for the team.
    - `owner` (string, required). Specifies owner for this management project webhook. Values: `project`.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
    - `eventTypes` (array of string, required, items 1–100, unique items, item length 1–128). Event types associated with this management project webhook.
    - `enabled` (boolean, required). Whether this feature is enabled.
    - `format` (string, required). Specifies format for this management project webhook. Values: `native`, `meta`.
    - `retryPolicy` (object, required). Specifies retry policy for this management project webhook.
      - `maximumAttempts` (integer, required, range 1–10). Specifies maximum attempts for this management webhook retry policy.
      - `backoff` (string, required). Specifies backoff for this management webhook retry policy. Values: `constant`, `linear`, `exponential`.
      - `initialDelaySeconds` (integer, required, range 1–3600). Specifies initial delay seconds for this management webhook retry policy.
    - `phoneOfflineStartDay` (integer, required, range 7–13). First day without the phone on which this endpoint receives session.phone_offline.
    - `headers` (array of object, required, max items 10). HTTP headers attached to the outgoing request.
      - `name` (string, required, length 1–128). Human-readable name for this resource.
    - `secret` (object, required). Specifies secret for this management project webhook.
      - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
      - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
      - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management project webhook mutation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhook": {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "owner": "project",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "url": "https://example.com",
      "eventTypes": [
        "string"
      ],
      "enabled": true,
      "format": "native",
      "retryPolicy": {
        "maximumAttempts": 1,
        "backoff": "constant",
        "initialDelaySeconds": 1
      },
      "phoneOfflineStartDay": 7,
      "headers": [
        {
          "name": "string"
        }
      ],
      "secret": {
        "version": 1,
        "createdAt": "2026-09-22T12:00:00Z",
        "previousValidUntil": "2026-09-22T12:00:00Z"
      },
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    },
    "operationId": null,
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Rotate team webhook secret

`POST https://api.polymorfa.com/platform/webhooks/{webhookId}/secret-rotations` (Platform API)

Required permission: `webhooks:manage`

Rotates the signing secret and returns the new secret once.

Team keys require `webhooks:manage`. Project tokens are not accepted.

### Path parameters

- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `overlapSeconds` (integer, range 0–86400). Specifies overlap seconds for this management rotate webhook secret input. Default: `3600`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/webhooks/<webhookId>/secret-rotations" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "overlapSeconds": 3600
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `secret` (string, required, nullable). Specifies secret for this management team webhook secret rotation receipt.
  - `secretAvailable` (boolean, required). Whether secret available.
  - `secretMetadata` (object, required). Specifies secret metadata for this management team webhook secret rotation receipt.
    - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
  - `idempotency` (object, required). Specifies idempotency for this management team webhook secret rotation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhookId": "00000000-0000-4000-8000-000000000000",
    "operationId": null,
    "secret": "string",
    "secretAvailable": true,
    "secretMetadata": {
      "version": 1,
      "createdAt": "2026-09-22T12:00:00Z",
      "previousValidUntil": "2026-09-22T12:00:00Z"
    },
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Test team webhook

`POST https://api.polymorfa.com/platform/webhooks/{webhookId}/tests` (Platform API)

Required permission: `webhooks:manage`

Creates a synthetic team event and a traceable webhook delivery.

Team keys require `webhooks:manage`. Project tokens are not accepted.

### Path parameters

- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `eventType` (string, pattern ^[a-z0-9][a-z0-9_.-]{0,127}$). Category assigned to event. Default: `"polymorfa.test"`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/webhooks/<webhookId>/tests" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "polymorfa.test"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `operationId` (string (uuid), required, format uuid). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management team webhook test receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.
  - `eventId` (string (uuid), required, format uuid). Identifier for the event.
  - `deliveryId` (string (uuid), required, format uuid). Identifier for the delivery.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "operationId": "00000000-0000-4000-8000-000000000000",
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "eventId": "00000000-0000-4000-8000-000000000000",
    "deliveryId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Rotate project webhook secret

`POST https://api.polymorfa.com/platform/projects/{projectId}/webhooks/{webhookId}/secret-rotations` (Platform API)

Required permission: `webhooks:manage`

Rotates the signing secret and returns the new secret once.

Requires `webhooks:manage`. Project tokens only access resources in their own project.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `overlapSeconds` (integer, range 0–86400). Specifies overlap seconds for this management rotate webhook secret input. Default: `3600`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>/secret-rotations" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "overlapSeconds": 3600
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `secret` (string, required, nullable). Specifies secret for this management project webhook secret rotation receipt.
  - `secretAvailable` (boolean, required). Whether secret available.
  - `secretMetadata` (object, required). Specifies secret metadata for this management project webhook secret rotation receipt.
    - `version` (integer, required, min 1). Specifies version for this management webhook signing secret metadata.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `previousValidUntil` (string (date-time), required, nullable, format date-time). Specifies previous valid until for this management webhook signing secret metadata.
  - `idempotency` (object, required). Specifies idempotency for this management project webhook secret rotation receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhookId": "00000000-0000-4000-8000-000000000000",
    "operationId": null,
    "secret": "string",
    "secretAvailable": true,
    "secretMetadata": {
      "version": 1,
      "createdAt": "2026-09-22T12:00:00Z",
      "previousValidUntil": "2026-09-22T12:00:00Z"
    },
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Test project webhook

`POST https://api.polymorfa.com/platform/projects/{projectId}/webhooks/{webhookId}/tests` (Platform API)

Required permission: `webhooks:manage`

Creates a synthetic project event and a traceable webhook delivery. An optional complete native envelope is accepted only with an exact HMS-enabled project session.

Requires `webhooks:manage`. Project tokens only access resources in their own project.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- One of:
  - `eventType` (object).
    - `eventType` (string, pattern ^[a-z0-9][a-z0-9_.-]{0,127}$). Category assigned to event. Default: `"polymorfa.test"`.
  - `Option 2` (object).
    - `eventType` (string, pattern ^[a-z0-9][a-z0-9_.-]{0,127}$). Category assigned to event.
    - `body` (object, required). Primary text content shown to the recipient.
      - `encoding` (string, required). Specifies encoding for this management encoded event payload. Values: `base64`.
      - `contentType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `video/mp4`, `audio/ogg`, or `application/pdf`). IANA media type that matches the payload. Values: `application/json`.
      - `data` (string (byte), required, max length 87384, format byte). Canonical base64 for the complete native webhook body; decoded bytes are limited to 65,536 bytes.
    - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>/tests" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "polymorfa.test"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `operationId` (string (uuid), required, format uuid). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management project webhook test receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.
  - `eventId` (string (uuid), required, format uuid). Identifier for the event.
  - `deliveryId` (string (uuid), required, format uuid). Identifier for the delivery.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "operationId": "00000000-0000-4000-8000-000000000000",
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "eventId": "00000000-0000-4000-8000-000000000000",
    "deliveryId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The retained payload is unavailable or no longer replayable.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Delete webhook

`DELETE https://api.polymorfa.com/messaging/webhooks/{id}` (Messaging API)

Required permission: `webhooks:manage`

**Required scope:** `webhooks:manage`

### Path parameters

- `id` (string, required). Identifier for this resource.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/messaging/webhooks/<id>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Webhook deleted
- `success` (boolean, required). Whether the request succeeded.
- `message` (string). Human-readable message associated with this result.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Delete team webhook

`DELETE https://api.polymorfa.com/platform/webhooks/{webhookId}` (Platform API)

Required permission: `webhooks:manage`

Deletes one team-owned webhook.

Team keys require `webhooks:manage`. Project tokens are not accepted.

### Path parameters

- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/webhooks/<webhookId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.
  - `deleted` (boolean, required). Whether deleted. Values: `true`.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management team webhook deletion receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhookId": "00000000-0000-4000-8000-000000000000",
    "deleted": true,
    "operationId": null,
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## Delete project webhook

`DELETE https://api.polymorfa.com/platform/projects/{projectId}/webhooks/{webhookId}` (Platform API)

Required permission: `webhooks:manage`

Deletes one webhook owned by the exact project.

Requires `webhooks:manage`. Project tokens only access resources in their own project.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `webhookId` (string (uuid), required, format uuid). Identifier for the webhook.
  - `deleted` (boolean, required). Whether deleted. Values: `true`.
  - `operationId` (string, required, nullable). Identifier used to retrieve the asynchronous operation.
  - `idempotency` (object, required). Specifies idempotency for this management project webhook deletion receipt.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `key` (string, required, length 1–255). Specifies key for this management idempotency receipt.
    - `replayed` (boolean, required). Whether replayed.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "webhookId": "00000000-0000-4000-8000-000000000000",
    "deleted": true,
    "operationId": null,
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```
