Setting up webhooks

Step-by-step instruction on how to configure webhooks

Written by Konstantine

Updated 3 years ago

In order to get real-time updates on customers and chats from your HelpCrunch account, you should properly setup webhooks. This article provides a step-by-step instruction on how to do that.

1️⃣ Get Your Webhook Signing Key

Go to Settings → Developers → Webhooks and find your HTTP Webhook Signing Key there.

Each webhook event is signed by HelpCrunch via an X-HelpCrunch-Signature header. This is obligatory and by decoding the signature you can verify that the event came from HelpCrunch.

The value of the X-HelpCrunch-Signature header is computed by creating a signature using the body of the JSON request and your HTTP Webhook Signing Key value.

The signature is the hexadecimal (40-byte) representation of an SHA-1 signature computed using the HMAC algorithm as defined in RFC2104. See example below.

"headers": {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-HelpCrunch-Signature": "att73h99zvs9ipdmaj2rmr4oi5jhtwubs6q6tfwr",
    "x-forwarded-for": "192.168.1.1",
    "x-forwarded-proto": "https",
    "x-forwarded-port": "443",
    "host": "5m4eybr2jdwhdqqx49oyhvb4scgc64mo6ijuewgy.m.pipedream.net",
    "x-amzn-trace-id": "Root=1-5m4eybr2jdwhdqqx49oyhvb4scgc64mo6ijuewgy",
    "content-length": "293",
    "user-agent": "GuzzleHttp/6.5.5 curl/7.52.1 PHP/7.3.8-1+0~20190807.43+debian9~1.gbp7731bf",
  },

2️⃣ Add Webhooks

To add a webhook, press Add Webhook button. You'll see the following popup.

Choose the Event Type you want to subscribe to and specify a publicly accessible URL (endpoint) that HelpCrunch should sent HTTP requests to.

Make sure to enter the full URL, including https://...

You can find the complete list of all webhook events you can subscribe to in the Webhook event types & models article.

3️⃣ Test And Debug Webhooks

You can easily test your webhooks with the third-party services like RequestBin. Before you add your own URL, you can use RequestBin to create a public endpoint to receive and inspect HTTP requests from HelpCrunch.

If you need to whitelist IP address to accept inbound webhook requests from HelpCrunch, use this one: 95.216.72.81

4️⃣ Process Webhook Requests

When you're done with testing, you should write a custom application code on your backend that runs in response to HelpCrunch webhook HTTP requests. After that you can edit your webhooks and change the test URL to your production endpoint. When done, just turn on your webhooks and you're ready to go.

Webhook events activated

Handling Webhook Events

For every webhook request you receive from HelpCrunch, you should send back one of the following response codes.

Response	Description	Action taken
200-299	Success	Webhook successfully delivered
410	Gone	Your endpoint or app is not available, so we mark the event as failed
4xx (except 410)	Client or server errors	We'll retry after 1 min, 5 min, 20 min, 60 min and 2 hours. If all retries fail, we mark the event as failed

If any webhook event is marked as failed 3 times in a row, it will be turned off and no more events will be sent for that webhook.

5️⃣ Unsubscribe From Specific Events

If you no longer need to get some specific events from HelpCrunch, you can just turn them off or completely delete them.

Read Next → Chat webhooks

Did this answer your question?