Webhook Subscriptions
Register your endpoint, choose events, rotate the signing secret, pause, and delete
These six operations manage the one endpoint that receives events for all your client orgs. What arrives there is documented in Webhooks.
Scope: PARTNER_ADMIN. All six accept either an API key holding that scope or a member login on the provider org (kind TECH_PROVIDER).
All of them take the subscription's ID as the GraphQL ID! scalar - not String - though the value is the same hex string.
registerPartnerWebhook
registerPartnerWebhook(url: String!, events: [OutboundWebhookEventName!]!): RegisteredPartnerWebhook!Registers an endpoint and returns its signing secret.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
url | String! | Yes | Your HTTPS endpoint. It receives events for every client org you manage. |
events | [OutboundWebhookEventName!]! | Yes | Which events to deliver, as enum names. See the event catalogue. |
Returns RegisteredPartnerWebhook!
| Field | Type | Description |
|---|---|---|
id | ID! | The subscription ID. Pass it to the other five operations. |
signingSecret | String! | The whsec_ secret used to verify signatures. Returned only here and on rotate. |
Example
mutation Register {
registerPartnerWebhook(
url: "https://api.crmco.com/wexio/webhook"
events: [MESSAGE_INBOUND_CREATED, MESSAGE_OUTBOUND_CREATED, CONTACT_MERGED, ORGANISATION_DELETED]
) {
id
signingSecret
}
}{
"data": {
"registerPartnerWebhook": {
"id": "6716b4121c34d0012ab89f22",
"signingSecret": "whsec_7Hn2QpV4rT8yB1eK5mZ9xL3sW6jD0aC"
}
}
}Store signingSecret immediately. It is never returned by partnerWebhooks. If you lose it, call rotatePartnerWebhookSecret and deploy the new one.
partnerWebhooks
partnerWebhooks: [PartnerWebhookOutput!]!Lists your subscriptions. Never returns a secret. Takes no arguments.
Returns [PartnerWebhookOutput!]!
| Field | Type | Description |
|---|---|---|
id | ID! | The subscription ID. |
url | String! | The registered endpoint. |
subscribedEvents | [OutboundWebhookEventName!]! | Events currently delivered. |
status | PartnerWebhookStatus! | ACTIVE or PAUSED. |
createdAt | DateTime | When it was registered. |
updatedAt | DateTime | Last change to the subscription. |
Example
query Hooks {
partnerWebhooks {
id
url
subscribedEvents
status
}
}{
"data": {
"partnerWebhooks": [
{
"id": "6716b4121c34d0012ab89f22",
"url": "https://api.crmco.com/wexio/webhook",
"subscribedEvents": ["MESSAGE_INBOUND_CREATED", "ORGANISATION_DELETED"],
"status": "ACTIVE"
}
]
}
}rotatePartnerWebhookSecret
rotatePartnerWebhookSecret(id: ID!): RotatedPartnerWebhookSecret!Issues a new signing secret for the subscription. The old secret stops verifying, so deploy the new one promptly.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
id | ID! | Yes | The subscription to rotate. |
Returns RotatedPartnerWebhookSecret! - signingSecret: String!, the new whsec_ secret. Shown once.
Example
mutation Rotate {
rotatePartnerWebhookSecret(id: "6716b4121c34d0012ab89f22") { signingSecret }
}{
"data": {
"rotatePartnerWebhookSecret": {
"signingSecret": "whsec_2Bf6LmQ9tX4vR7wZ1yH8jN0pS3dG5kA"
}
}
}setPartnerWebhookEvents
setPartnerWebhookEvents(id: ID!, events: [OutboundWebhookEventName!]!): PartnerWebhookOutput!Replaces the subscribed event list - it is not additive. Send the complete list you want.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
id | ID! | Yes | The subscription to update. |
events | [OutboundWebhookEventName!]! | Yes | The full replacement list. Passing [] stops all deliveries. |
Returns PartnerWebhookOutput! - the updated subscription.
Example
mutation Events {
setPartnerWebhookEvents(
id: "6716b4121c34d0012ab89f22"
events: [MESSAGE_INBOUND_CREATED, MESSAGE_OUTBOUND_CREATED, CONTACT_MERGED, CONTACT_SPLIT, ORGANISATION_DELETED]
) {
id
subscribedEvents
}
}setPartnerWebhookStatus
setPartnerWebhookStatus(id: ID!, status: PartnerWebhookStatus!): PartnerWebhookOutput!Pauses or resumes delivery without losing the subscription or its secret. While PAUSED, matching events are dropped, not queued - they are not replayed when you resume.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
id | ID! | Yes | The subscription to update. |
status | PartnerWebhookStatus! | Yes | ACTIVE or PAUSED. |
Returns PartnerWebhookOutput! - the updated subscription.
Example
mutation Status {
setPartnerWebhookStatus(id: "6716b4121c34d0012ab89f22", status: PAUSED) {
id
status
}
}deletePartnerWebhook
deletePartnerWebhook(id: ID!): Boolean!Deletes the subscription and its secret permanently. Use setPartnerWebhookStatus if you only want to stop deliveries temporarily.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
id | ID! | Yes | The subscription to delete. |
Returns Boolean! - true when deleted.
Example
mutation Delete {
deletePartnerWebhook(id: "6716b4121c34d0012ab89f22")
}{ "data": { "deletePartnerWebhook": true } }