Webhook endpoints
The team webhook object
Attributes
idstring (uuid)requiredIdentifier for this resource.
teamIdstring (uuid)requiredIdentifier for the team.
ownerstringrequiredSpecifies owner for this management team webhook.
Allowed valuesteamprojectIdstringrequirednullableIdentifier of the Polymorfa project that owns this resource.
urlstring (uri)requiredmax length2048URL associated with this resource.
eventTypesarray of stringrequireditems1–100unique itemsitem length1–128Event types associated with this management team webhook.
enabledbooleanrequiredWhether this feature is enabled.
formatstringrequiredSpecifies format for this management team webhook.
Allowed valuesnativemetaretryPolicyobjectrequiredSpecifies retry policy for this management team webhook.
Show 3 child fields
phoneOfflineStartDayintegerrequiredrange7–13First day without the phone on which this endpoint receives session.phone_offline.
headersarray of objectrequiredmax items10HTTP headers attached to the outgoing request.
Show 1 child field
secretobjectrequiredSpecifies secret for this management team webhook.
Show 3 child fields
createdAtstring (date-time)requiredISO 8601 timestamp when this resource was created.
updatedAtstring (date-time)requiredISO 8601 timestamp when this resource was last updated.
{
"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)requiredIdentifier for this resource.
teamIdstring (uuid)requiredIdentifier for the team.
ownerstringrequiredSpecifies owner for this management project webhook.
Allowed valuesprojectprojectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
urlstring (uri)requiredmax length2048URL associated with this resource.
eventTypesarray of stringrequireditems1–100unique itemsitem length1–128Event types associated with this management project webhook.
enabledbooleanrequiredWhether this feature is enabled.
formatstringrequiredSpecifies format for this management project webhook.
Allowed valuesnativemetaretryPolicyobjectrequiredSpecifies retry policy for this management project webhook.
Show 3 child fields
phoneOfflineStartDayintegerrequiredrange7–13First day without the phone on which this endpoint receives session.phone_offline.
headersarray of objectrequiredmax items10HTTP headers attached to the outgoing request.
Show 1 child field
secretobjectrequiredSpecifies secret for this management project webhook.
Show 3 child fields
createdAtstring (date-time)requiredISO 8601 timestamp when this resource was created.
updatedAtstring (date-time)requiredISO 8601 timestamp when this resource was last updated.
{
"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
idstringrequiredIdentifier for this resource.
tenantIdstringrequiredIdentifier of the team that owns this resource.
sessionstringIdentifier of the connected Polymorfa session.
urlstringrequiredURL associated with this resource.
eventsarray of stringrequiredEvents returned or subscribed to by this operation.
retriesobjectrequiredRetry policy applied after a failed delivery attempt.
Show 3 child fields
headersarray of objectrequiredHTTP headers attached to the outgoing request.
Show 2 child fields
enabledbooleanrequiredWhether this feature is enabled.
formatstringSpecifies format for this native webhook.
Allowed valuesnativemetaphoneOfflineStartDayintegerrange7–13Specifies phone offline start day for this native webhook.
createdAtstringrequiredISO 8601 timestamp when this resource was created.
{
"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
- Base URL
https://api.polymorfa.com- Required permission
webhooks:manage
Body
sessionstringIdentifier of the connected Polymorfa session.
urlstring (uri)requiredURL associated with this resource.
eventsarray of stringmax items1000Event types this webhook subscribes to.
hmacKeystringHMAC key used to verify signed payloads.
retriesobjectRetry policy applied after a failed delivery attempt.
Show 3 child fields
headersarray of objectmax items1000HTTP 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 valuesnativemetaphoneOfflineStartDayintegerrange7–13First 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
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
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"
}'{
"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
- 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–255Specifies idempotency key for this header parameter.
Body
urlstring (uri)requiredlength1–2048URL associated with this resource.
eventTypesarray of stringrequireditems1–100unique itemsitem length1–128Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
enabledbooleanWhether this feature is enabled.
DefaulttrueformatstringSpecifies format for this management create team webhook input.
Allowed valuesnativemetaDefault"native"retryPolicyobjectSpecifies retry policy for this management create team webhook input.
Show 3 child fields
phoneOfflineStartDayintegerrange7–13First 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.
Default10headersarray of objectmax items10HTTP headers attached to the outgoing request.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured 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`).
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"
]
}'{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
urlstring (uri)requiredlength1–2048URL associated with this resource.
eventTypesarray of stringrequireditems1–100unique itemsitem length1–128Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
enabledbooleanWhether this feature is enabled.
DefaulttrueformatstringSpecifies format for this management create project webhook input.
Allowed valuesnativemetaDefault"native"retryPolicyobjectSpecifies retry policy for this management create project webhook input.
Show 3 child fields
phoneOfflineStartDayintegerrange7–13First 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.
Default10headersarray of objectmax items10HTTP headers attached to the outgoing request.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured 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`).
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"
]
}'{
"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
- Base URL
https://api.polymorfa.com- Required permission
webhooks:manage
Responses
200Webhook list
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataarray of objectrequiredStructured 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
curl "https://api.polymorfa.com/messaging/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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–128Category assigned to event.
enabledbooleanWhether this feature is enabled.
limitintegerrange1–100Specifies limit for this query parameter.
Default25cursorstringSpecifies cursor for this query parameter.
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 14 child fields
pageobjectrequiredSpecifies 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.
curl "https://api.polymorfa.com/platform/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
Query parameters
eventTypestringlength1–128Category assigned to event.
enabledbooleanWhether this feature is enabled.
limitintegerrange1–100Specifies limit for this query parameter.
Default25cursorstringSpecifies cursor for this query parameter.
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 14 child fields
pageobjectrequiredSpecifies 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.
curl "https://api.polymorfa.com/platform/projects/<projectId>/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- Base URL
https://api.polymorfa.com- Required permission
webhooks:manage
Path parameters
idstringrequiredIdentifier for this resource.
Responses
200Webhook details
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
curl "https://api.polymorfa.com/messaging/webhooks/<id>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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)requiredIdentifier for the webhook.
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/webhooks/<webhookId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
webhookIdstring (uuid)requiredIdentifier for the webhook.
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/projects/<projectId>/webhooks/<webhookId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- Base URL
https://api.polymorfa.com- Required permission
webhooks:manage
Path parameters
idstringrequiredIdentifier for this resource.
Body
urlstring (uri)URL associated with this resource.
eventsarray of stringmax items1000Event types this webhook subscribes to.
hmacKeystringHMAC key used to verify signed payloads.
retriesobjectRetry policy applied after a failed delivery attempt.
Show 3 child fields
headersarray of objectmax items1000HTTP headers attached to the outgoing request.
Show 2 child fields
enabledbooleanWhether this feature is enabled.
formatstringSpecifies format for this native update webhook request.
Allowed valuesnativemetaphoneOfflineStartDayintegerrange7–13First 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
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
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
}'{
"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
- 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)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
urlstring (uri)length1–2048URL associated with this resource.
eventTypesarray of stringitems1–100unique itemsitem length1–128Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
enabledbooleanWhether this feature is enabled.
formatstringSpecifies format for this management update team webhook input.
Allowed valuesnativemetaretryPolicyobjectSpecifies retry policy for this management update team webhook input.
Show 3 child fields
phoneOfflineStartDayintegerrange7–13First 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 items10HTTP headers attached to the outgoing request.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured 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`).
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"
}
]
}'{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
webhookIdstring (uuid)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
urlstring (uri)length1–2048URL associated with this resource.
eventTypesarray of stringitems1–100unique itemsitem length1–128Names reserved for internal use cannot be newly subscribed. Existing stored entries may be preserved during updates but never match deliveries.
enabledbooleanWhether this feature is enabled.
formatstringSpecifies format for this management update project webhook input.
Allowed valuesnativemetaretryPolicyobjectSpecifies retry policy for this management update project webhook input.
Show 3 child fields
phoneOfflineStartDayintegerrange7–13First 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 items10HTTP headers attached to the outgoing request.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured 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`).
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"
}
]
}'{
"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
- 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)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
overlapSecondsintegerrange0–86400Specifies overlap seconds for this management rotate webhook secret input.
Default3600
Responses
200Success
dataobjectrequiredStructured 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`).
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
}'{
"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
- 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)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies 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
dataobjectrequiredStructured 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`).
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"
}'{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
webhookIdstring (uuid)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
overlapSecondsintegerrange0–86400Specifies overlap seconds for this management rotate webhook secret input.
Default3600
Responses
200Success
dataobjectrequiredStructured 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`).
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
}'{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
webhookIdstring (uuid)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies 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
dataobjectrequiredStructured 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.
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"
}'{
"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
- Base URL
https://api.polymorfa.com- Required permission
webhooks:manage
Path parameters
idstringrequiredIdentifier for this resource.
Responses
200Webhook deleted
successbooleanrequiredWhether the request succeeded.
messagestringHuman-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
curl -X DELETE "https://api.polymorfa.com/messaging/webhooks/<id>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true
}Delete team webhook
- 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)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Responses
200Success
dataobjectrequiredStructured 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`).
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>"{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
webhookIdstring (uuid)requiredIdentifier for the webhook.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Responses
200Success
dataobjectrequiredStructured 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`).
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>"{
"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"
}
}
}