Skip to main content
POST
Create a webhook subscription

Authorizations

Authorization
string
header
required

Use a workspace API key in the Authorization header. Keys use pk_live_<key_id> for production and pk_test<key_id>_ for test mode.

Headers

Idempotency-Key
string

Optional retry key for safely replaying create requests. Reusing the same key with a different request body returns 409.

Required string length: 8 - 255
Example:

"8db8e596-7c1a-4fd5-a728-4d6c99f4e66b"

Body

application/json
url
string<uri>
required

HTTPS endpoint that will receive signed webhook deliveries.

Example:

"https://example.com/protodesk/webhooks"

events
enum<string>[]
required
Minimum array length: 1
Available options:
customer.created,
customer.updated,
conversation.created,
conversation.updated,
conversation.assigned,
conversation.resolved,
conversation.read,
message.created,
message.delivered,
message.failed
Example:
status
enum<string>
default:active
Available options:
active,
disabled
metadata
object
Example:

Response

Created webhook subscription. The signing secret is returned only in this response.

id
string
required
Example:

"wh_x6q5vl75f5d53m7oet2k4r5w6a"

url
string<uri>
required
Example:

"https://example.com/protodesk/webhooks"

events
enum<string>[]
required
Available options:
customer.created,
customer.updated,
conversation.created,
conversation.updated,
conversation.assigned,
conversation.resolved,
conversation.read,
message.created,
message.delivered,
message.failed
status
enum<string>
required
Available options:
active,
disabled
metadata
object
required
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
secret
string | null

Signing secret; returned only when the webhook is created, null on reads.

Example:

"whsec_pz6kyr2ftwsn6c6q3a4oky2d35txmgaj3t35u2quy4ielzqro3za"