Legacy Mailbox API 1.0 is deprecated

Legacy Mailbox API 1.0 was deprecated on November 20, 2019. Please use Mailbox API 2.0 going forward. If you have any questions or need help with the new API, please reach out.

Create Webhook

  • REST Method: POST
  • URL: https://api.helpscout.net/v1/hooks.json
  • Content-Type: application/json

Clients may create and configure up to one webhook per company. A webhook may be configured to receive multiple event notifications (e.g. conversation created, note added). Each request to this API will replace the existing webhook (if any) with the one specified in the request body.

For more details about handling Help Scout's webhooks, see this overview.

Request Fields

Name Type Required Notes
url String Y The callback URL where Help Scout will post your webhook events. This is the script or location where you'll handle the data received from Help Scout.
events List Y The list of events to subscribe to; the full list is detailed here.
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.

Example Request

  "url": "https://example.com/helpscout",
  "events": [
  "secret": "mZ9XbGHodX"


Response Name Type Notes
Header Status Integer 201
Header Location String A location header is returned, but the webhooks API does not support a GET end point at this time.

Example Response

Status: 201 Created
Location: https://api.helpscout.net/v1/hooks/{id}.json