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": [
"convo.created",
"convo.customer.reply.created",
"convo.assigned",
"convo.deleted",
"convo.note.created"
],
"secret": "mZ9XbGHodX"
}Response
| 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