Create Webhook

When creating a web hook, it’s possible to set a notification flag. When a web hook fires, the payload does not contain the changed entity but rather just a resource URL that can be used to fetch the entity. See Notification payload for its format.

Request

POST /v2/webhooks HTTP/1.1
Authorization: Bearer oauth_token
Content-Type: application/json

{
  "url" : "https:\\/\\/example.com/helpscout",
  "events" : [ "convo.assigned" ],
  "secret" : "mZ9XbGHodX",
  "payloadVersion" : "V2",
  "label" : "cool webhook"
}

Request fields

Path Type Required Description
url String Y URL that will be called when of the events occurs
events Array Y List of defined events, one of:
beacon.chat.created
beacon.chat.customer.replied
convo.agent.reply.created
convo.ai-answers-email.reply.created
convo.ai-answers-email.resolution
convo.assigned
convo.created
convo.custom-fields
convo.customer.reply.created
convo.deleted
convo.merged
convo.moved
convo.note.created
convo.status
convo.tags
customer.created
customer.deleted
customer.updated
message.survey.response.received
organization.created
organization.deleted
organization.updated
satisfaction.ratings
tag.created
tag.deleted
tag.updated
user.status.changed
notification Boolean N Notification web hooks only send the URL of the changed resource, not the payload body. See Notification payload.
label String N Label associated with this Webhook for better clarity.
payloadVersion String N Version of the payload delivered to the url. Options are V2 (deprecated) and V3. V3 preserves system_user type in conversation payloads. Defaults to V2 if omitted.
mailboxIds Array N An array of mailbox identifiers. The webhook will trigger for actions on conversations in any of the specified mailboxes. If not provided, the webhook will trigger for actions on conversations in all mailboxes.
secret String Y A randomly-generated (by you) string of 40 characters or less used to create signatures for each webhook method.
Help Scout uses this secret key to generate a signature for each webhook message.
When the message is received at your callback URL, you can calculate a signature and compare to the one Help Scout sends.
If the signatures match, you know it’s from Help Scout.

Notification payload

When notification is true, the request body contains these two fields instead of the changed entity:

{
  "resource_url": "https://api.helpscout.net/v2/conversations/3443157477",
  "event_type": "convo.created"
}
Field Type Description
resource_url String URL of the resource the event is about. Request it to get the resource’s current state.
event_type String The event that fired. It matches the X-HelpScout-Event header.

The request has the same headers and signature as any other webhook, so you can verify it the same way.

The resource behind resource_url depends on the event. Every URL starts with https://api.helpscout.net.

Events resource_url path Endpoint
convo.* /v2/conversations/{conversationId} Get Conversation
customer.* /v2/customers/{customerId} Get Customer
satisfaction.ratings /v2/ratings/{ratingId} Get Satisfaction Rating
beacon.chat.* /v2/chats/{chatId} Get Chat
tag.* /v2/tags/{tagId} Get Tag by ID
user.status.changed /v2/users/{userId}/status Get user status

For convo.deleted, customer.deleted and tag.deleted, resource_url points at the resource that was deleted.

Response

HTTP/1.1 201 Created
Resource-ID: 10
Location: https://api.helpscout.net/v2/webhooks/10
↑Back to top