API Reference/Webhooks/List all webhooks

List all webhooks

GEThttps://api.postpress.ai/v1/webhooks

Returns a paginated list of the webhooks registered on your postpress account. Each item is either an automatic webhook (`type: AUTO`) wired to account events, or a manual trigger (`type: TRIGGER`) fired from a chat or message context.

Authorization

X-API-KEYstringrequired
API key from your postpress dashboard. Sent as a request header.

Query parameters

limitintegeroptional
1 to 250. Defaults to 100.
cursorstringoptional
Pagination cursor returned by a previous call.

Response 200 OK

objectstringWebhookListrequired
itemsarray of objectsrequired
items object
(variant) AUTO webhookobject
Standard auto-fired webhook triggered by account/messaging/calendar events.
(variant) AUTO webhook object
objectstringWebhookrequired
idstringrequired
namestring
Display name.
enabledbooleanrequired
request_urlstringrequired
URL postpress will POST to.
formatstringrequired
jsonform
Encoding of the delivered payload.
account_idsarray of objectsrequired
Accounts this webhook listens on.
account_ids object
idstringrequired
The connected account id.
namestring
typestringrequired
GOOGLEGOOGLE_CALENDARICLOUDLINKEDINMAILMOBILEOUTLOOKTWITTERWHATSAPPSLACKTELEGRAM
headersarray of objectsrequired
Extra HTTP headers postpress will send.
headers object
keystringrequired
valuestringrequired
dataarray of objectsrequired
Payload field mapping. The allowed `key` values depend on the event family.
data object
namestringrequired
Output property name. Overrides the original key name in the payload.
keystringrequired
Source field to include. Allowed values depend on the event family (messaging, relation, mail, mail tracking, calendar).
eventsarray of strings
message_receivedmessage_readmessage_reactionmessage_editedmessage_deletedmessage_deliverednew_relationmail_sentmail_receivedmail_movedmail_openedmail_link_clickedcreation_successcreation_faildeletedreconnectedsync_successstoppedokconnectingerrorcredentialspermissionscalendar_event_createdcalendar_event_updatedcalendar_event_deleted
Events this webhook subscribes to.
typestringAUTOrequired
(variant) TRIGGER webhookobject
User-defined trigger fired from the chat surface (message or chat context).
(variant) TRIGGER webhook object
objectstringWebhookrequired
idstringrequired
namestring
Display name.
enabledbooleanrequired
request_urlstringrequired
URL postpress will POST to.
formatstringrequired
jsonform
Encoding of the delivered payload.
account_idsarray of objectsrequired
Accounts this webhook listens on.
account_ids object
idstringrequired
The connected account id.
namestring
typestringrequired
GOOGLEGOOGLE_CALENDARICLOUDLINKEDINMAILMOBILEOUTLOOKTWITTERWHATSAPPSLACKTELEGRAM
headersarray of objectsrequired
Extra HTTP headers postpress will send.
headers object
keystringrequired
valuestringrequired
dataarray of objectsrequired
Payload field mapping. The allowed `key` values depend on the event family.
data object
namestringrequired
Output property name. Overrides the original key name in the payload.
keystringrequired
Source field to include. Allowed values depend on the event family (messaging, relation, mail, mail tracking, calendar).
eventsarray of strings
message_receivedmessage_readmessage_reactionmessage_editedmessage_deletedmessage_deliverednew_relationmail_sentmail_receivedmail_movedmail_openedmail_link_clickedcreation_successcreation_faildeletedreconnectedsync_successstoppedokconnectingerrorcredentialspermissionscalendar_event_createdcalendar_event_updatedcalendar_event_deleted
Events this webhook subscribes to.
typestringTRIGGERrequired
triggerobjectrequired
trigger object
iconstringrequired
WebhookIconSettingsInputIconLeakAddIconDiversity2IconAutoFixHighIconSignPostIconShutterSpeedIconSyncAltIconWhatsAppIconLinkedInIconImportExportIconPodcastsIconCableIconCalendarIcon
namestringrequired
contextstringrequired
MESSAGECHAT
cursorstringrequired
Pagination cursor. `null` on the last page.

Example request

curl --request GET \
  --url 'https://api.postpress.ai/api/v1/webhooks?limit=100' \
  --header 'X-API-KEY: pp_live_...' \
  --header 'accept: application/json'

Example response

{
  "object": "WebhookList",
  "items": [
    {
      "object": "Webhook",
      "id": "wh_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
      "name": "Inbound DMs - production",
      "enabled": true,
      "request_url": "https://app.example.com/hooks/postpress",
      "format": "json",
      "account_ids": [
        { "id": "acc_linkedin_01HXYZ4QK3WJ8FN3M6QH7TZ8GR", "name": "Jordan (LinkedIn)", "type": "LINKEDIN" }
      ],
      "headers": [
        { "key": "Authorization", "value": "Bearer s3cr3t" }
      ],
      "data": [
        { "name": "from",    "key": "sender" },
        { "name": "body",    "key": "message" },
        { "name": "chat",    "key": "chat_id" },
        { "name": "subject", "key": "subject" }
      ],
      "events": ["message_received", "message_reaction"],
      "type": "AUTO"
    },
    {
      "object": "Webhook",
      "id": "wh_01HXYZ4QK3WJ8FN3M6QH7TZ8H7",
      "name": "Send to CRM",
      "enabled": true,
      "request_url": "https://app.example.com/hooks/crm",
      "format": "form",
      "account_ids": [],
      "headers": [],
      "data": [
        { "name": "thread", "key": "chat_id" },
        { "name": "text",   "key": "message" }
      ],
      "events": [],
      "type": "TRIGGER",
      "trigger": {
        "icon": "WebhookIcon",
        "name": "Send to CRM",
        "context": "CHAT"
      }
    }
  ],
  "cursor": null
}

Errors

Every error response follows the same envelope:

titlestringrequired
Short error title.
detailstringoptional
Human-readable explanation.
instancestringoptional
Request identifier for support.
typestringrequired
Error type identifier.
statusnumberrequired
HTTP status code.
400 Bad Request8 types

The query string is malformed or a parameter is invalid.

  • errors/invalid_parameters - One or more parameters are invalid.
  • errors/malformed_request - The request is malformed.
  • errors/content_too_large - The request is too large.
  • errors/invalid_url - A URL field is invalid.
  • errors/too_many_characters - A string field exceeds the allowed length.
  • errors/unescaped_characters - A field contains characters that must be encoded.
  • errors/missing_parameters - A required field is missing.
  • errors/limit_too_high - `limit` exceeds 250.
401 Unauthorized13 types

API key is missing, expired, or otherwise invalid.

  • errors/missing_credentials - API key is missing from the request.
  • errors/invalid_credentials - API key is invalid.
  • errors/expired_credentials - API key has expired. Rotate it from the dashboard.
  • errors/insufficient_privileges - This resource is out of your API-key scopes.
  • errors/multiple_sessions - Multiple sessions detected on the same account.
  • errors/wrong_account - The credentials do not match the correct account.
  • errors/invalid_proxy_credentials - The provided proxy credentials are invalid.
  • errors/invalid_checkpoint_solution - The checkpoint resolution did not pass successfully.
  • errors/checkpoint_error - The checkpoint does not appear to be resolvable.
  • errors/expired_link - This link has expired. Generate a new one.
  • errors/disconnected_account - The account is disconnected from the provider service.
  • errors/disconnected_feature - The feature you're trying to reach is disconnected.
  • errors/invalid_credentials_but_valid_account_imap - IMAP/SMTP credentials are invalid but the account is otherwise valid.
403 Forbidden9 types

Authenticated but the action is not allowed on this account.

  • errors/insufficient_permissions - Insufficient permissions to perform the request.
  • errors/account_restricted - The account has been restricted by the provider.
  • errors/account_mismatch - This action cannot be done with your account.
  • errors/unknown_authentication_context - An additional step seems necessary to complete login.
  • errors/session_mismatch - Token user id does not match client session id.
  • errors/feature_not_subscribed - The requested feature has not been subscribed.
  • errors/subscription_required - A subscription is required to use this feature.
  • errors/resource_access_restricted - You don't have access to this resource.
  • errors/action_required - An additional step is required.
500 Internal Server Error3 types

Something went wrong on our side.

  • errors/unexpected_error - Something went wrong.
  • errors/provider_error - The provider is experiencing operational problems. Retry later.
  • errors/authentication_intent_error - The current authentication intent was killed after failure.
503 Service Unavailable5 types

postpress is temporarily unable to handle the request.

  • errors/no_client_session - No client session is currently running.
  • errors/no_channel - No channel to client session.
  • errors/no_handler - Handler missing for that request.
  • errors/network_down - Network is down on the server side. Retry shortly.
  • errors/service_unavailable - Service temporarily unavailable. Retry later.
504 Gateway Timeout1 types

The upstream provider did not respond in time.

  • errors/request_timeout - Request timed out. Retry, and contact support if it persists.
Updated May 2026