Webhooks Manager - Implementation

Frequently Asked Questions

How can I implement webhooks?

1. Create a GET method of your receiver webhook server, which supports authentication. Must return 200 for verification and health check purposes. For details, see What are the GET request requirements for webhook endpoint verification?

2. Create a POST method of the same receiver webhook server, where data will be received.

3. Create a base URL from the Punchh platform via Data Sharing > Outbound Webhooks > Webhooks tab > click the Base URL button > click the Add New URL button. In the Admin Email field, specify the email address that will receive notifications such as suspension, deactivation, and activation.

4. Create a webhook from the Punchh platform via Data Sharing > Outbound Webhooks > Webhooks tab > click the Create Webhook button. Choose the base URL and authentication method, subscribe to the desired events, and finally verify and submit to activate.

What are the GET request requirements for webhook endpoint verification?

When a business subscribes to receive webhook events from Punchh, the business's webhook HTTPS server must support a GET method sent to the base URL that will receive outbound webhook events from the Punchh server. The server must return 200 for verification. The GET request verifies the HTTPS server configuration that has subscribed to receive webhook events from Punchh.

1. To configure webhooks, the business needs a working HTTPS web server to consume requests to the base URL for a domain that the business owns (e.g., https://parhooks.example.com). The base URL is configured in the Punchh platform under Data Sharing > Outbound Webhooks > Webhooks tab. These requests are the webhook events.

2. The HTTPS server must support one of the four authentication methods: basic, bearer, HMAC-SHA1, or HMAC-SHA256. See Which types of authentication are used while configuring webhooks?

3. The HTTPS server must handle a GET method sent to the base URL from Punchh, which includes an Authorization header for the chosen authentication method to authenticate the API request. For example, if the web server that receives webhook events supports bearer token authentication and if Punchh sends a GET request to the web server with a BEARER_TOKEN of value xyzxyzxxyyzz, at https://parhooks.example.com, then the web server needs to respond to this request.

Here is a sample cURL GET request. The header requirements for the various authentication configurations are described in this topic.

curl --request GET \  
--url https://parhooks.example.com \  
--header 'Accept: application/json' \  
--header 'Authorization: bearer xyzxyzxxyyzz'

4. When the GET message is sent to the HTTPS server, the following response codes must be handled:

  • 2xx - Success. This means that the business's web server is configured properly.

  • 404 - Fail. Here is a sample failure message:

    {
"message": "Something went wrong!"
}

5. On the Punchh platform, navigate to Data Sharing > Outbound Webhooks > Webhooks tab > click the Create Webhook button. Configure the information for the webhook including the Base URL attribute, and select the Active check box. When you click Submit, Punchh sends a GET request to the HTTPS server (as mentioned in Step 4) to ensure that the web server has been properly configured. The webhook configuration will be saved only if the GET message response code is 2xx.

See the "Configure Webhooks" section in the Webhooks article on the Punchh Support Portal. You can view this article on the Punchh Support Portal if you have access to a Punchh production environment. If you already have access to a production environment for a brand, please follow the instructions here to access the Punchh Support Portal.

6. After receiving the success response for the GET request, Punchh sends actual webhook events using POST requests to the specified webhook endpoint under the base URL. These POST requests contain the data related to the event. The Web server must be configured to handle POST methods.

Which types of authentication are used while configuring webhooks?

The following authentication types are supported:

  • none: pass blank authentication header. Not recommended. Use any one of the authentication methods below for security reasons.

  • basic: pass authentication header as Authentication: basic [token]

  • bearer: pass authentication header as Authentication: bearer [token]

  • HMAC-SHA1: calculate the token=hmacSHA1(uri+body, secret) and pass the authentication header as Authentication: hmac [token]. To identify the source, one more header is passed as x-pch-key . If you do not need/have a client, you can pass an alternative string such as punchh_webhooks or <business_name>_webhook

  • HMAC-SHA256: calculate the token=hmacSHA256(uri+body, secret) and pass the authentication header as Authentication: hmac [token]. To identify the source, one more header is passed as x-pch-key . If you do not need/have a client, you can pass an alternative string such as punchh_webhooks or <business_name>_webhook

Where can I find Webhooks Manager in the Punchh Platform? 

If you cannot see Inbound Webhooks or Outbound Webooks in the left navigation menu in the Punchh platform, then you probably do not have access. Webhooks management will need to be enabled for your business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.

Where can I find the “Add New URL” button while trying to add a base URL? 

You may not have access to that section of the Punchh platform. Contact your Punchh representative.

Previous
Webhook Delivery - Error Handling and Retry Logic
Next
Braze Webhooks Adapter Overview