Skip to content
Shortcut: /, ⌘K or Ctrl+K

Webhook endpoints

View as Markdown

The team webhook object

Attributes

  • idstring (uuid)required

    Identifier for this resource.

  • teamIdstring (uuid)required

    Identifier for the team.

  • ownerstringrequired

    Specifies owner for this management team webhook.

    Allowed valuesteam
  • projectIdstringrequirednullable

    Identifier of the Polymorfa project that owns this resource.

  • urlstring (uri)requiredmax length2048

    URL associated with this resource.

  • eventTypesarray of stringrequireditems1–100unique itemsitem length1–128

    Event types associated with this management team webhook.

  • enabledbooleanrequired

    Whether this feature is enabled.

  • formatstringrequired

    Specifies format for this management team webhook.

    Allowed valuesnativemeta
  • retryPolicyobjectrequired

    Specifies retry policy for this management team webhook.

    Show 3 child fields
  • phoneOfflineStartDayintegerrequiredrange7–13

    First day without the phone on which this endpoint receives session.phone_offline.

  • headersarray of objectrequiredmax items10

    HTTP headers attached to the outgoing request.

    Show 1 child field
  • secretobjectrequired

    Specifies secret for this management team webhook.

    Show 3 child fields
  • createdAtstring (date-time)required

    ISO 8601 timestamp when this resource was created.

  • updatedAtstring (date-time)required

    ISO 8601 timestamp when this resource was last updated.

The team webhook object
{
  "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

  • idstring (uuid)required

    Identifier for this resource.

  • teamIdstring (uuid)required

    Identifier for the team.

  • ownerstringrequired

    Specifies owner for this management project webhook.

    Allowed valuesproject
  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • urlstring (uri)requiredmax length2048

    URL associated with this resource.

  • eventTypesarray of stringrequireditems1–100unique itemsitem length1–128

    Event types associated with this management project webhook.

  • enabledbooleanrequired

    Whether this feature is enabled.

  • formatstringrequired

    Specifies format for this management project webhook.

    Allowed valuesnativemeta
  • retryPolicyobjectrequired

    Specifies retry policy for this management project webhook.

    Show 3 child fields
  • phoneOfflineStartDayintegerrequiredrange7–13

    First day without the phone on which this endpoint receives session.phone_offline.

  • headersarray of objectrequiredmax items10

    HTTP headers attached to the outgoing request.

    Show 1 child field
  • secretobjectrequired

    Specifies secret for this management project webhook.

    Show 3 child fields
  • createdAtstring (date-time)required

    ISO 8601 timestamp when this resource was created.

  • updatedAtstring (date-time)required

    ISO 8601 timestamp when this resource was last updated.

The project webhook object
{
  "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

  • idstringrequired

    Identifier for this resource.

  • tenantIdstringrequired

    Identifier of the team that owns this resource.

  • sessionstring

    Identifier of the connected Polymorfa session.

  • urlstringrequired

    URL associated with this resource.

  • eventsarray of stringrequired

    Events returned or subscribed to by this operation.

  • retriesobjectrequired

    Retry policy applied after a failed delivery attempt.

    Show 3 child fields
  • headersarray of objectrequired

    HTTP headers attached to the outgoing request.

    Show 2 child fields
  • enabledbooleanrequired

    Whether this feature is enabled.

  • formatstring

    Specifies format for this native webhook.

    Allowed valuesnativemeta
  • phoneOfflineStartDayintegerrange7–13

    Specifies phone offline start day for this native webhook.

  • createdAtstringrequired

    ISO 8601 timestamp when this resource was created.

The Messaging API webhook object
{
  "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/messaging/webhooksMessaging API
Base URL
https://api.polymorfa.com
Required permission
webhooks:manage

Body

  • sessionstring

    Identifier of the connected Polymorfa session.

  • urlstring (uri)required

    URL associated with this resource.

  • eventsarray of stringmax items1000

    Event types this webhook subscribes to.

  • hmacKeystring

    HMAC key used to verify signed payloads.

  • retriesobject

    Retry policy applied after a failed delivery attempt.

    Show 3 child fields
  • headersarray of objectmax items1000

    HTTP headers attached to the outgoing request.

    Show 2 child fields
  • formatstring

    "native" (default) = Polymorfa event envelope. "meta" = Meta Cloud API webhook shape (object/entry/changes/value), signed with X-Hub-Signature-256.

    Allowed valuesnativemeta
  • phoneOfflineStartDayintegerrange7–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.

Responses

  • 201Webhook created
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 11 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /messaging/webhookscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/messaging/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com"
}'
Response
{
  "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"
  }
}

Create team webhook

POST/platform/webhooksPlatform API
Base URL
https://api.polymorfa.com
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.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • urlstring (uri)requiredlength1–2048

    URL associated with this resource.

  • eventTypesarray of stringrequireditems1–100unique itemsitem length1–128

    Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.

  • enabledboolean

    Whether this feature is enabled.

    Default true
  • formatstring

    Specifies format for this management create team webhook input.

    Allowed valuesnativemeta
    Default "native"
  • retryPolicyobject

    Specifies retry policy for this management create team webhook input.

    Show 3 child fields
  • phoneOfflineStartDayintegerrange7–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
  • headersarray of objectmax items10

    HTTP headers attached to the outgoing request.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 5 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
POST /platform/webhookscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/webhooks" \
  -H "Authorization: Bearer YOUR_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"
  ]
}'
Response
{
  "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
  }
}

Create project webhook

POST/platform/projects/{projectId}/webhooksPlatform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • urlstring (uri)requiredlength1–2048

    URL associated with this resource.

  • eventTypesarray of stringrequireditems1–100unique itemsitem length1–128

    Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.

  • enabledboolean

    Whether this feature is enabled.

    Default true
  • formatstring

    Specifies format for this management create project webhook input.

    Allowed valuesnativemeta
    Default "native"
  • retryPolicyobject

    Specifies retry policy for this management create project webhook input.

    Show 3 child fields
  • phoneOfflineStartDayintegerrange7–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
  • headersarray of objectmax items10

    HTTP headers attached to the outgoing request.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 5 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
POST /platform/projects/{projectId}/webhookscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/webhooks" \
  -H "Authorization: Bearer YOUR_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"
  ]
}'
Response
{
  "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
  }
}

List webhooks

GET/messaging/webhooksMessaging API
Base URL
https://api.polymorfa.com
Required permission
webhooks:manage

Responses

  • 200Webhook list
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 11 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /messaging/webhookscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
    }
  ]
}

List team webhooks

GET/platform/webhooksPlatform API
Base URL
https://api.polymorfa.com
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

  • eventTypestringlength1–128

    Category assigned to event.

  • enabledboolean

    Whether this feature is enabled.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • cursorstring

    Specifies cursor for this query parameter.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 14 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/webhookscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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
  }
}

List project webhooks

GET/platform/projects/{projectId}/webhooksPlatform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

Query parameters

  • eventTypestringlength1–128

    Category assigned to event.

  • enabledboolean

    Whether this feature is enabled.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • cursorstring

    Specifies cursor for this query parameter.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 14 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/projects/{projectId}/webhookscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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
  }
}

Get webhook

GET/messaging/webhooks/{id}Messaging API
Base URL
https://api.polymorfa.com
Required permission
webhooks:manage

Path parameters

  • idstringrequired

    Identifier for this resource.

Responses

  • 200Webhook details
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 11 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /messaging/webhooks/{id}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/webhooks/<id>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
  }
}

Get team webhook

GET/platform/webhooks/{webhookId}Platform API
Base URL
https://api.polymorfa.com
Required permission
webhooks:read

Returns one team-owned webhook without secret values.

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

Path parameters

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 14 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/webhooks/{webhookId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/webhooks/<webhookId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
  }
}

Get project webhook

GET/platform/projects/{projectId}/webhooks/{webhookId}Platform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 14 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/projects/{projectId}/webhooks/{webhookId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
  }
}

Update webhook

PUT/messaging/webhooks/{id}Messaging API
Base URL
https://api.polymorfa.com
Required permission
webhooks:manage

Path parameters

  • idstringrequired

    Identifier for this resource.

Body

  • urlstring (uri)

    URL associated with this resource.

  • eventsarray of stringmax items1000

    Event types this webhook subscribes to.

  • hmacKeystring

    HMAC key used to verify signed payloads.

  • retriesobject

    Retry policy applied after a failed delivery attempt.

    Show 3 child fields
  • headersarray of objectmax items1000

    HTTP headers attached to the outgoing request.

    Show 2 child fields
  • enabledboolean

    Whether this feature is enabled.

  • formatstring

    Specifies format for this native update webhook request.

    Allowed valuesnativemeta
  • phoneOfflineStartDayintegerrange7–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.

Responses

  • 200Webhook updated
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 11 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
PUT /messaging/webhooks/{id}cURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/messaging/webhooks/<id>" \
  -H "Authorization: Bearer YOUR_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
}'
Response
{
  "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"
  }
}

Update team webhook

PATCH/platform/webhooks/{webhookId}Platform API
Base URL
https://api.polymorfa.com
Required permission
webhooks:manage

Updates settings without rotating the signing secret.

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

Path parameters

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • urlstring (uri)length1–2048

    URL associated with this resource.

  • eventTypesarray of stringitems1–100unique itemsitem length1–128

    Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.

  • enabledboolean

    Whether this feature is enabled.

  • formatstring

    Specifies format for this management update team webhook input.

    Allowed valuesnativemeta
  • retryPolicyobject

    Specifies retry policy for this management update team webhook input.

    Show 3 child fields
  • phoneOfflineStartDayintegerrange7–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.

  • headersarray of objectmax items10

    HTTP headers attached to the outgoing request.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 3 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
PATCH /platform/webhooks/{webhookId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PATCH "https://api.polymorfa.com/platform/webhooks/<webhookId>" \
  -H "Authorization: Bearer YOUR_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"
    }
  ]
}'
Response
{
  "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"
    }
  }
}

Update project webhook

PATCH/platform/projects/{projectId}/webhooks/{webhookId}Platform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • urlstring (uri)length1–2048

    URL associated with this resource.

  • eventTypesarray of stringitems1–100unique itemsitem length1–128

    Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.

  • enabledboolean

    Whether this feature is enabled.

  • formatstring

    Specifies format for this management update project webhook input.

    Allowed valuesnativemeta
  • retryPolicyobject

    Specifies retry policy for this management update project webhook input.

    Show 3 child fields
  • phoneOfflineStartDayintegerrange7–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.

  • headersarray of objectmax items10

    HTTP headers attached to the outgoing request.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 3 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
PATCH /platform/projects/{projectId}/webhooks/{webhookId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PATCH "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>" \
  -H "Authorization: Bearer YOUR_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"
    }
  ]
}'
Response
{
  "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"
    }
  }
}

Rotate team webhook secret

POST/platform/webhooks/{webhookId}/secret-rotationsPlatform API
Base URL
https://api.polymorfa.com
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

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • overlapSecondsintegerrange0–86400

    Specifies overlap seconds for this management rotate webhook secret input.

    Default 3600

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 6 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
POST /platform/webhooks/{webhookId}/secret-rotationscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/webhooks/<webhookId>/secret-rotations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "overlapSeconds": 3600
}'
Response
{
  "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"
    }
  }
}

Test team webhook

POST/platform/webhooks/{webhookId}/testsPlatform API
Base URL
https://api.polymorfa.com
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

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • eventTypestringpattern^[a-z0-9][a-z0-9_.-]{0,127}$

    Category assigned to event.

    Default "polymorfa.test"

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
POST /platform/webhooks/{webhookId}/testscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/webhooks/<webhookId>/tests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "polymorfa.test"
}'
Response
{
  "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"
  }
}

Rotate project webhook secret

POST/platform/projects/{projectId}/webhooks/{webhookId}/secret-rotationsPlatform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • overlapSecondsintegerrange0–86400

    Specifies overlap seconds for this management rotate webhook secret input.

    Default 3600

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 6 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
POST /platform/projects/{projectId}/webhooks/{webhookId}/secret-rotationscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>/secret-rotations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "overlapSeconds": 3600
}'
Response
{
  "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"
    }
  }
}

Test project webhook

POST/platform/projects/{projectId}/webhooks/{webhookId}/testsPlatform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

One of
  • eventTypestringpattern^[a-z0-9][a-z0-9_.-]{0,127}$

    Category assigned to event.

    Default "polymorfa.test"

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The retained payload is unavailable or no longer replayable.
POST /platform/projects/{projectId}/webhooks/{webhookId}/testscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>/tests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "polymorfa.test"
}'
Response
{
  "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"
  }
}

Delete webhook

DELETE/messaging/webhooks/{id}Messaging API
Base URL
https://api.polymorfa.com
Required permission
webhooks:manage

Path parameters

  • idstringrequired

    Identifier for this resource.

Responses

  • 200Webhook deleted
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
DELETE /messaging/webhooks/{id}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/messaging/webhooks/<id>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}

Delete team webhook

DELETE/platform/webhooks/{webhookId}Platform API
Base URL
https://api.polymorfa.com
Required permission
webhooks:manage

Deletes one team-owned webhook.

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

Path parameters

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
DELETE /platform/webhooks/{webhookId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/webhooks/<webhookId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>"
Response
{
  "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"
    }
  }
}

Delete project webhook

DELETE/platform/projects/{projectId}/webhooks/{webhookId}Platform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
DELETE /platform/projects/{projectId}/webhooks/{webhookId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>"
Response
{
  "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"
    }
  }
}