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 URI that can be used to fetch the entity.

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.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
satisfaction.ratings
tag.created
tag.deleted
tag.updated
notification Boolean N Notification web hooks only send URI of the changed resource, not the payload body.
label String N Label associated with this Webhook for better clarity.
payloadVersion String N Version of the payload delivered to the url. Only option is V2 and can be omitted because it’s the default.
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.

Response

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