API Reference/Webhooks/Create a webhook

Create a webhook

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

Register a new webhook on your postpress account. The body is a discriminated union on `source`: pick the family of events you want to receive (`messaging`, `users`, `account_status`, `email`, `email_tracking`, or `calendar_event`) and the available `events` and `data.key` values change accordingly.

Authorization

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

Request body

Every variant accepts the same envelope of common fields. The `source` discriminator decides which `events` enum and which `data.key` enum apply.

(variant) Messaging webhookobject
Inbound chat/DM events. Default `events: ["message_received"]`.
(variant) Messaging webhook object
sourcestringmessagingrequired
Discriminator. Picks the kind of data the webhook delivers.
request_urlstringrequired
URL postpress will POST to when an event fires.
namestring
Display name. Echoed back in the delivered payload as `webhook_name`.
formatstring
jsonform
Payload encoding. Defaults to `json`.
enabledboolean
Defaults to `true`.
account_idsarray of strings
Restrict the webhook to specific accounts. Omit to receive events from every account, current and future.
eventsarray of strings
message_receivedmessage_readmessage_reactionmessage_editedmessage_deletedmessage_delivered
Events to subscribe to. See section default below.
headersarray of objects
Extra HTTP headers postpress will send with every delivery.
headers object
keystringrequired
valuestringrequired
dataarray of objects
Payload field mapping. Use this to rename or trim the delivered payload.
data object
namestringrequired
Output property name. Overrides the original key name in the payload.
keystringrequired
account_idaccount_typeaccount_infochat_idtimestampwebhook_namemessage_idmessagereactionreaction_senderread_bysenderis_senderattendeesattachmentssubjectprovider_chat_idprovider_message_idis_eventchat_pinnedquotedis_forwardedchat_content_typemessage_typeis_groupfolder
Source field to include in the payload.
(variant) Users webhookobject
Network changes. Default `events: ["new_relation"]`.
(variant) Users webhook object
sourcestringusersrequired
Discriminator. Picks the kind of data the webhook delivers.
request_urlstringrequired
URL postpress will POST to when an event fires.
namestring
Display name. Echoed back in the delivered payload as `webhook_name`.
formatstring
jsonform
Payload encoding. Defaults to `json`.
enabledboolean
Defaults to `true`.
account_idsarray of strings
Restrict the webhook to specific accounts. Omit to receive events from every account, current and future.
eventsarray of stringsnew_relation
Events to subscribe to. See section default below.
headersarray of objects
Extra HTTP headers postpress will send with every delivery.
headers object
keystringrequired
valuestringrequired
dataarray of objects
Payload field mapping. Use this to rename or trim the delivered payload.
data object
namestringrequired
Output property name. Overrides the original key name in the payload.
keystringrequired
account_idaccount_typewebhook_nametimestampuser_provider_iduser_full_nameuser_public_identifieruser_profile_urluser_picture_url
Source field to include in the payload.
(variant) Account status webhookobject
Account lifecycle. Defaults cover the usual statuses except CONNECTING, OK, and STOPPED.
(variant) Account status webhook object
sourcestringaccount_statusrequired
Discriminator. Picks the kind of data the webhook delivers.
request_urlstringrequired
URL postpress will POST to when an event fires.
namestring
Display name. Echoed back in the delivered payload as `webhook_name`.
formatstring
jsonform
Payload encoding. Defaults to `json`.
enabledboolean
Defaults to `true`.
account_idsarray of strings
Restrict the webhook to specific accounts. Omit to receive events from every account, current and future.
eventsarray of strings
creation_successcreation_faildeletedreconnectedsync_successstoppedokconnectingerrorcredentialspermissions
Events to subscribe to. See section default below.
headersarray of objects
Extra HTTP headers postpress will send with every delivery.
headers object
keystringrequired
valuestringrequired
(variant) Email webhookobject
Inbound and outbound mail. Default `events: ["mail_received"]`.
(variant) Email webhook object
sourcestringemailrequired
Discriminator. Picks the kind of data the webhook delivers.
request_urlstringrequired
URL postpress will POST to when an event fires.
namestring
Display name. Echoed back in the delivered payload as `webhook_name`.
formatstring
jsonform
Payload encoding. Defaults to `json`.
enabledboolean
Defaults to `true`.
account_idsarray of strings
Restrict the webhook to specific accounts. Omit to receive events from every account, current and future.
eventsarray of strings
mail_sentmail_receivedmail_moved
Events to subscribe to. See section default below.
headersarray of objects
Extra HTTP headers postpress will send with every delivery.
headers object
keystringrequired
valuestringrequired
dataarray of objects
Payload field mapping. Use this to rename or trim the delivered payload.
data object
namestringrequired
Output property name. Overrides the original key name in the payload.
keystringrequired
email_idaccount_idwebhook_namedatefrom_attendeeto_attendeescc_attendeesbcc_attendeesreply_to_attendeessubjectbodybody_plainmessage_idprovider_idtracking_idread_dateis_completein_reply_tohas_attachmentsattachmentsfoldersroleoriginthread_iddeprecated_id
Source field to include in the payload.
(variant) Email tracking webhookobject
Open and click tracking. Default `events: ["mail_opened"]`.
(variant) Email tracking webhook object
sourcestringemail_trackingrequired
Discriminator. Picks the kind of data the webhook delivers.
request_urlstringrequired
URL postpress will POST to when an event fires.
namestring
Display name. Echoed back in the delivered payload as `webhook_name`.
formatstring
jsonform
Payload encoding. Defaults to `json`.
enabledboolean
Defaults to `true`.
account_idsarray of strings
Restrict the webhook to specific accounts. Omit to receive events from every account, current and future.
eventsarray of strings
mail_openedmail_link_clicked
Events to subscribe to. See section default below.
headersarray of objects
Extra HTTP headers postpress will send with every delivery.
headers object
keystringrequired
valuestringrequired
dataarray of objects
Payload field mapping. Use this to rename or trim the delivered payload.
data object
namestringrequired
Output property name. Overrides the original key name in the payload.
keystringrequired
event_idtracking_idtypedateemail_idaccount_idipuser_agenturllabelcustom_domain
Source field to include in the payload.
(variant) Calendar event webhookobject
Calendar event changes. Default `events: ["calendar_event_created"]`.
(variant) Calendar event webhook object
sourcestringcalendar_eventrequired
Discriminator. Picks the kind of data the webhook delivers.
request_urlstringrequired
URL postpress will POST to when an event fires.
namestring
Display name. Echoed back in the delivered payload as `webhook_name`.
formatstring
jsonform
Payload encoding. Defaults to `json`.
enabledboolean
Defaults to `true`.
account_idsarray of strings
Restrict the webhook to specific accounts. Omit to receive events from every account, current and future.
eventsarray of strings
calendar_event_createdcalendar_event_updatedcalendar_event_deleted
Events to subscribe to. See section default below.
headersarray of objects
Extra HTTP headers postpress will send with every delivery.
headers object
keystringrequired
valuestringrequired
dataarray of objects
Payload field mapping. Use this to rename or trim the delivered payload.
data object
namestringrequired
Output property name. Overrides the original key name in the payload.
keystringrequired
account_idaccount_typeidical_uidmaster_event_idcalendar_idcreated_atupdated_attitlebodylocationis_cancelledis_all_dayis_attendees_list_hiddenattendeesstartendrecurrenceorganizerconference_idconferencevisibilitytransparencyevent_typecolor
Source field to include in the payload.

Response 201 Created

objectstringWebhookCreatedrequired
webhook_idstringrequired

Example request

curl --request POST \
  --url 'https://api.postpress.ai/api/v1/webhooks' \
  --header 'X-API-KEY: pp_live_...' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "source": "messaging",
    "request_url": "https://app.example.com/hooks/postpress",
    "name": "Inbound DMs - production",
    "format": "json",
    "enabled": true,
    "account_ids": ["acc_linkedin_01HXYZ4QK3WJ8FN3M6QH7TZ8GR"],
    "events": ["message_received", "message_reaction"],
    "headers": [{ "key": "Authorization", "value": "Bearer s3cr3t" }],
    "data": [
      { "name": "from",    "key": "sender" },
      { "name": "body",    "key": "message" },
      { "name": "chat",    "key": "chat_id" },
      { "name": "subject", "key": "subject" }
    ]
  }'

Example response

{
  "object": "WebhookCreated",
  "webhook_id": "wh_01HXYZ4QK3WJ8FN3M6QH7TZ8GR"
}

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 body is malformed or a field is invalid.

  • errors/invalid_parameters - One or more fields are invalid (e.g. unknown `source`, `data.key` not allowed for this `source`).
  • errors/malformed_request - The request is malformed.
  • errors/content_too_large - The request is too large.
  • errors/invalid_url - `request_url` is not a valid URL.
  • 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 (`request_url`, `source`) is missing.
  • errors/limit_too_high - A list field exceeds the allowed maximum.
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.

  • 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.
404 Not Found2 types

One of the targeted resources does not exist.

  • errors/resource_not_found - An entry in `account_ids` does not match any connected account.
  • errors/invalid_resource_identifier - An account id is malformed.
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