Webhooks

Methods, permissions, request fields and response schemas for webhooks.

Read and search

Retrieve current records, history and status.

List webhook destinations{data:Endpoint[],eventTypes:string[],workerEnabled:boolean}. Up to ten endpoints per organization. Endpoint={id,name,url,events,enabled,disabledReason,createdAt,updatedAt}; no secret is returned.GET/developer/webhooks

Token scope webhooks:readActor permission ownerAction type read

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{data:Endpoint[],eventTypes:string[],workerEnabled:boolean}. Up to ten endpoints per organization. Endpoint={id,name,url,events,enabled,disabledReason,createdAt,updatedAt}; no secret is returned.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/developer/webhooks" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string",
                "minLength": 0,
                "maxLength": 80
              },
              "url": {
                "type": "string",
                "minLength": 0,
                "maxLength": 2048
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 0,
                  "maxLength": 5000
                }
              },
              "enabled": {
                "type": "boolean"
              },
              "disabledReason": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "id",
              "name",
              "url",
              "events",
              "enabled"
            ],
            "additionalProperties": true
          },
          "maxItems": 10
        },
        "eventTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 0,
            "maxLength": 5000
          }
        },
        "workerEnabled": {
          "type": "boolean"
        }
      },
      "required": [
        "data",
        "eventTypes",
        "workerEnabled"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Read webhook delivery attempts{data:[{cursor,id,eventId,status,attempts,replayCount,nextAttemptAt,lastStatus,lastError,deliveredAt,createdAt}],nextCursor,lastCursor,hasMore}.GET/developer/webhooks/:id/deliveries

Token scope webhooks:readActor permission ownerAction type read

Pagination: limit 1–100, default 50; cursor is an opaque decimal string. Keep lastCursor even when hasMore=false to resume later.

Path parameters

Field	Type	Description and constraints
`id`Required	string · uuid	Resource UUID scoped to the current organization.

Query parameters

Field	Type	Description and constraints
`limit`Optional	integer	Minimum 1 · Maximum 100
`cursor`Optional	string	Opaque decimal sequence cursor from this feed's prior response. Send as a string. At least 1 characters · At most 19 characters · Pattern: ^[0-9]+$

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{data:[{cursor,id,eventId,status,attempts,replayCount,nextAttemptAt,lastStatus,lastError,deliveredAt,createdAt}],nextCursor,lastCursor,hasMore}.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/developer/webhooks/$ID/deliveries?limit=20" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "cursor": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "eventId": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "in_flight",
                  "delivered",
                  "dead"
                ]
              },
              "attempts": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "replayCount": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "nextAttemptAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "lastStatus": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "lastError": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "deliveredAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "cursor",
              "id",
              "eventId",
              "status",
              "attempts",
              "replayCount"
            ],
            "additionalProperties": true
          }
        },
        "nextCursor": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 5000
        },
        "lastCursor": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 5000
        },
        "hasMore": {
          "type": "boolean"
        }
      },
      "required": [
        "data",
        "nextCursor",
        "lastCursor",
        "hasMore"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Create and import

Add records, prepare imports or start a new setup.

Create a webhook destinationRegister an HTTPS event destination and capture its signing secret once.POST/developer/webhooks

Token scope webhooks:writeActor permission ownerAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Before you use it

The events array must contain distinct supported event types. HTTPS/public-address validation runs before saving. Delivery requires the worker and encryption configuration.

Request body

Field	Type	Description and constraints
`name`Required	string	At least 1 characters · At most 80 characters
`url`Required	string · uri	Public HTTPS destination on port 443. Private/reserved addresses and redirects are rejected; server rechecks DNS at delivery. At least 1 characters · At most 2048 characters
`events`Required	array of string	At least 1 items · At most 9 items · Unique items

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Endpoint plus signingSecret, shown once. Keep the signing secret in your bot's secret store; it is not an API token.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

umask 077
curl -X POST "$BASE/developer/webhooks" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Growth Bot events","url":"https://bot.example.com/webhooks/allprofiles","events":["chat.message.created","rental.updated"]}' \
  --output webhook-created.json

Full JSON request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "format": "uri",
      "description": "Public HTTPS destination on port 443. Private/reserved addresses and redirects are rejected; server rechecks DNS at delivery."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "profile.created",
          "profile.updated",
          "profile.deleted",
          "rental.created",
          "rental.updated",
          "rental.deleted",
          "chat.message.created",
          "chat.message.deleted",
          "webhook.test"
        ]
      },
      "maxItems": 9,
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": [
    "name",
    "url",
    "events"
  ],
  "additionalProperties": false
}

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string",
          "minLength": 0,
          "maxLength": 80
        },
        "url": {
          "type": "string",
          "minLength": 0,
          "maxLength": 2048
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 0,
            "maxLength": 5000
          }
        },
        "enabled": {
          "type": "boolean"
        },
        "disabledReason": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 5000
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "signingSecret": {
          "type": "string",
          "minLength": 0,
          "maxLength": 100
        }
      },
      "required": [
        "id",
        "signingSecret"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Update and configure

Change existing records, assignments and configuration.

Edit or disable a webhookChange a destination or pause new deliveries by disabling it.PATCH/developer/webhooks/:id

Token scope webhooks:writeActor permission ownerAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`id`Required	string · uuid	Resource UUID scoped to the current organization.

Request body

Field	Type	Description and constraints
`name`Optional	string	At least 1 characters · At most 80 characters
`url`Optional	string · uri	Public HTTPS destination on port 443. Private/reserved addresses and redirects are rejected; server rechecks DNS at delivery. At least 1 characters · At most 2048 characters
`events`Optional	array of string	At least 1 items · At most 9 items · Unique items
`enabled`Optional	boolean

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Updated endpoint; disabling stops new deliveries.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X PATCH "$BASE/developer/webhooks/$ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "format": "uri",
      "description": "Public HTTPS destination on port 443. Private/reserved addresses and redirects are rejected; server rechecks DNS at delivery."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "profile.created",
          "profile.updated",
          "profile.deleted",
          "rental.created",
          "rental.updated",
          "rental.deleted",
          "chat.message.created",
          "chat.message.deleted",
          "webhook.test"
        ]
      },
      "maxItems": 9,
      "minItems": 1,
      "uniqueItems": true
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [],
  "additionalProperties": false
}

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string",
          "minLength": 0,
          "maxLength": 80
        },
        "url": {
          "type": "string",
          "minLength": 0,
          "maxLength": 2048
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 0,
            "maxLength": 5000
          }
        },
        "enabled": {
          "type": "boolean"
        },
        "disabledReason": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 5000
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "url",
        "events",
        "enabled"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Lifecycle and actions

Manage transitions, delivery and provider workflows.

Queue a test webhookQueue a test event, then inspect delivery attempts to confirm remote receipt.POST/developer/webhooks/:id/test

Token scope webhooks:writeActor permission ownerAction type external

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`id`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{eventId,deliveryId,status:'queued'}. A queue result is not proof of remote receipt; check delivery status.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/developer/webhooks/$ID/test" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "eventId": {
          "type": "string",
          "format": "uuid"
        },
        "deliveryId": {
          "type": "string",
          "format": "uuid"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued"
          ]
        }
      },
      "required": [
        "eventId",
        "deliveryId",
        "status"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Replay a completed or failed deliveryRequeue a completed or failed attempt; the recipient must deduplicate event IDs.POST/developer/webhooks/:id/deliveries/:deliveryId/replay

Token scope webhooks:writeActor permission ownerAction type external

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`id`Required	string · uuid	Resource UUID scoped to the current organization.
`deliveryId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{id,eventId,status:'queued'}. Only dead or delivered attempts can be replayed; recipients must deduplicate by event ID.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/developer/webhooks/$ID/deliveries/$DELIVERY_ID/replay" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "eventId": {
          "type": "string",
          "format": "uuid"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued"
          ]
        }
      },
      "required": [
        "id",
        "eventId",
        "status"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Remove and disconnect

Remove a record, revoke access or end a connection.

Delete a webhook destination{deleted:true,id}. Removes destination and stops delivery.DELETE/developer/webhooks/:id

Token scope webhooks:writeActor permission ownerAction type destructive

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`id`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{deleted:true,id}. Removes destination and stops delivery.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X DELETE "$BASE/developer/webhooks/$ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "deleted": {
          "type": "boolean"
        },
        "id": {
          "type": "string",
          "format": "uuid"
        }
      },
      "required": [
        "deleted",
        "id"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.