# Webhooks

In addition to accessing resources, GoDaddy Poynt Cloud APIs also provide webhook notifications for the state change of each resource to the registered endpoints.

Applications can register their own endpoints as a webhook URL for events and developers can do it programmatically.

Additionally, GoDaddy Poynt APIs provide a way to obtain a list of all the notifications sent in the last 30 days so the applications can always make sure that merchants didn’t miss any notifications that they would need to process.

# Webhook Registration

# Request Example:

curl -v https://services.poynt.net/hooks \
-H "Poynt-Request-Id: <request id>" \
-H "api-version: 1.2" \
-H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: BEARER <access token>" \
-d '
{
        "applicationId": "urn:aid:6bcee3b0-ced0-4263-ac4e-f783acc9857e",
        "businessId": "569e957c-57a7-4d54-a72a-9e8f3296adad",
        "deliveryUrl": "http://www.mysite.com/webhook_listener.php",
        "secret": "not-the-secret-you-know",
        "eventTypes":[
	        "ORDER_OPENED",
	        "ORDER_COMPLETED",
	        "ORDER_CANCELLED",
	        "ORDER_UPDATED"
        ]
}
'

# Response Example:

{
    "active": true,
    "applicationId": "urn:aid:6bcee3b0-ced0-4263-ac4e-f783acc9857e",
    "businessId": "569e957c-57a7-4d54-a72a-9e8f3296adad",
    "createdAt": "2015-09-17T03:41:54Z",
    "deliveryUrl": "http://www.mysite.com/webhook_listener.php",
    "eventTypes": [
        "ORDER_OPENED",
        "ORDER_COMPLETED",
        "ORDER_CANCELLED",
        "ORDER_UPDATED"
    ],
    "id": "dbd29830-a67f-419b-a1d5-777a228543d6",
    "secret": "********",
    "updatedAt": "2015-09-17T03:41:54Z"
}

# Webhook Validation

When a specific event occurs, GoDaddy Poynt sends a webhook to the registered listener URL which will look similar to the block below:

Accept-Encoding: gzip,deflate
User-Agent: Apache-HttpClient/4.5 (Java/1.8.0_45-internal)
Connection: close
Host: www.mysite.com
Content-Length: 660
Poynt-Webhook-Signature: PkaykJxe3c5rHtZjcfBKWLk2khA=
Content-Type: application/json

{
    "applicationId": "urn:aid:6bdee3b0-ced0-4263-ac4e-f783acc9857e",
    "businessId": "469e957c-57a7-4d54-a72a-9e8f3296adad",
    "createdAt": "2015-09-15T20:00:44Z",
    "deviceId": "urn:tid:7e113874-9c3e-3d45-9c37-bde91ebe60e8",
    "eventType": "ORDER_COMPLETED",
    "hookId": "3574d16a-671c-47e3-ac0b-06dc5878abdc",
    "id": "77c6d7f7-2eeb-4ed0-9cb7-d1a846473cfc",
    "links": [
        {
            "href": "https://services.poynt.net/businesses/469e957c-57a7-4d54-a72a-9e8f3296adad/orders/d297262c-014f-1000-01e4-3c85d2679731",
            "method": "GET",
            "rel": "resource"
        }
    ],
    "resource": "/orders",
    "resourceId": "d297262c-014f-1000-01e4-3c85d2679731",
    "storeId": "c2855b41-1dd5-4ecc-8258-f0c89ae40338",
    "updatedAt": "2015-09-15T20:00:44Z"
}

To validate the authenticity of the webhook payload, you will need to create a base64 encoded binary SHA1 HMAC of the payload and compare it to the value of the Poynt-Webhook-Signature HTTP header sent in the webhook request.

Below is an example of how this can be done using openssl:

bash$ echo -n '<webhook json object>' | openssl sha1 -hmac "not-the-secret-you-know" -binary | base64 PkaykJxe3c5rHtZjcfBKWLk2khA=

Please keep in mind that GoDaddy Poynt only waits for 2 seconds to receive an acknowledgement from your webhook listener (i.e. HTTP 200 response). If we don't receive a response, the delivery will be re-attempted. To address this, we recommend making sure your webhook listener logic can de-dupe multiple requests.

TIP

If you would like to learn more about this topic, you can refer to our Python Sample Application (opens new window).

← Post-transaction Actions Subscriptions API Integration →