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

Copy 
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.
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

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