Akkroo
  1. Support
  2. Developers
  3. Webhooks

Webhooks

Understanding & Using Webhooks

Webhooks are a way to let Akkroo to call a script or send some data to your own web server when a person registers at an event or when payload is captured.

An example of how this might be useful is as follows,

  • Event: a person arrives at an event and registers onto the guestlist
  • Action: Akkroo sends a payload to a URL on your website, letting you instantly create a user account for that person

Other uses could include:

  • Updating a live statistics display in your office
  • Sending an SMS message
  • Printing a conference label or badge

Each of these tasks would require additional coding on your part, but Webhooks provide a great and simple way to start extending Akkroo today. For more advanced tasks, you might want to consider our REST API.

Getting Started

The first stage is setting up a Webhook URL on your account. Currently setting up this Webhook URL is a manual task for our support team, so drop us a support ticket or email when you are ready. Note that the URL must be visible to the web-at-large (and not just a local URL that you can access), for example,

  • Correct: http://www.example.com/my-webhook-script.php
  • Incorrect: http://localhost/my-webhook-script.php

Webhooks can be established on a per-event basis.

Implementation details

Akkroo will perform a HTTP POST to the URL you have specified on any of the actions listed. The POST request body contains a JSON encoded object which might look something like this:

{
	"type":"registration",
	"method":"create",
	"hash":"9f86d0818808...d6c15b0f0a08",
	"payloadEncrypted":true,
	"payload":"ZGZoanNiZGZo...c2Rmc2Rmc2Rm",
	"envKey":"GRDff2sdDD...KLh44fiuBMWG"
}

Your webhook receiver must respond as defined in expected response

Webhook Content

Property Type Description
type String
The type of action that has occurred
method String
The action that occurred. One of "create", "update" or "delete"
timestamp String
An RFC 1123 formatted GMT timestamp for when the event occurred
hash String
A salted hash of the JSON representation of the payload and the secret you provide us with. This allows you to verify the integrity of the payload once received. Learn how to check the hash.
payloadEncrypted Boolean
A flag to specify if the attached payload has been encrypted or not
payload String, Array
The webhook payload, which contains an array of resources in a format defined for the type. if payloadEncrypted is true, the payload will be encrypted and Base64 encoded.
envKey String
The envelope key for the encrypted payload. Base64 encoded.

Actions

Type Methods Description
registration create, update, delete
Actions occurring on a registration belonging to an event

Formats

Once you have retrieved the decrypted the payload from the request body, the result will be an array of resources.

The format of these are individual to the type of webhook and the method e.g. Create, Update, Delete. Each is explained below.

Note: you may receive notifications of single or multiple registration records at the same time within the payload. The payload will always be an array of resources.

Notification of Creation (new data collected)
{
   "type": "registrations",
   "method": "create",
   "timestamp": "Wed, 03 Sep 2014 14:21:59 GMT",
   "hash": "x3IXqNQ1032bc76tdfgb1a530d34a00945eaf7a6d25af1031a07b6bdff094df7c0f9b",
   "payloadEncrypted": false,
   "payload": [
      {
         "id": "540asda7ogasdf68t24f8e",
         "resource": {
            "isCheckIn": true,
            "appUserID": null,
            "source": "upload",
            "eventID": 160,
            "values": {
               "firstName": {
                  "value": "Greg"
               },
               "lastName": {
                  "value": "Goodguy"
               },
               "email": {
                  "value": "greggoodguy@example.com"
               },
               "fullName": {
                  "value": "Greg Goodguy"
               }
            },
            "companyID": 1,
            "lastModified": 1409754119,
            "created": 1409754119,
            "id": "540724sdfsad4c24f8e"
         }
      },
      {
         "id": "547d8sofg78s0e10c24f8f",
         "resource": {
            "isCheckIn": true,
            "appUserID": null,
            "source": "upload",
            "eventID": 160,
            "values": {
               "firstName": {
                  "value": "Johnny"
               },
               "lastName": {
                  "value": "Appleseed"
               },
               "email": {
                  "value": "johnnyappleseed@example.com"
               },
               "fullName": {
                  "value": "Johnny Appleseed"
               }
            },
            "companyID": 1,
            "lastModified": 1409754119,
            "created": 1409754119,
            "id": "540724sd2dsfsadf8f"
         }
      }
   ]
}
Notification of Updates
{
   "type": "registrations",
   "method": "update",
   "timestamp": "Wed, 03 Sep 2014 14:22:53 GMT",
   "hash": "uOOenb3ex8b1b035f2e6sdfsdfsdfs2f66c1ed341c7979d605f601d1aab1343",
   "payloadEncrypted": false,
   "payload": [
      {
         "id": "540724asdf4353340e10c24f8e",
         "resource": {
            "appUserID": 140903453365,
            "companyID": 1,
            "created": 1409754119,
            "deviceID": 1434252090318,
            "eventID": 160,
            "isCheckIn": true,
            "lastModified": 1409754173,
            "source": "upload",
            "timeArrived": 1409754173644,
            "values": {
               "email": {
                  "value": "johnnyappleseed@example.com"
               },
               "firstName": {
                  "value": "Johnny"
               },
               "fullName": {
                  "value": "Johnny Appleseed"
               },
               "lastName": {
                  "value": "Appleseed"
               }
            },
            "id": "df3072sdfs40e10c24f8e"
         },
         "previousResourceAttributes": {
            "appUserID": null
         }
      }
   ]
}
Notification of Deletion
{
   "type": "registrations",
   "method": "delete",
   "timestamp": "Wed, 03 Sep 2014 16:15:12 GMT",
   "hash": "ZKtGeUcl1V983748027438fdghdsaa5d65108e3175581a3sd8d948d",
   "payloadEncrypted": false,
   "payload": [
      {
         "id": "5407240sdfsr4t40e10c24f8e"
      }
   ]
}

Hash details

In the content of the webhook, we provide a hash so you can check that the payload is accurate and not corrupted.

We generate the hash provided in the webhook in the following way:

  1. We generate a random salt of 10 alphanumeric characters
  2. We concatenate in this order: the salt, the secret you provided us with (if any), and the JSON representation of the payload resource.
  3. We perform a SHA256 hash on the string
  4. We prepend the 10 character salt

To verify the hash from the webhook, you should remove salt from the first 10 characters of the hash, then perform steps 2 onwards and compare the result to the hash provided.

Note: that if the payload has been encrypted it will need to be decrypted first. If it is not encrypted it will need to be JSON encoded.

Expected response

If you have given us a webhook URL, that URL must respond with a 200 OK response with the following response body:

{"success":true}

Akkroo will attempt to send the data to the webhook URL repeatedly at regular intervals until receiving such a response.

Encryption options

We strongly recommend you use HTTPS for all webhook communication with us. If you cannot use HTTPS for some reason, we can encrypt the webhook using keys.

If you generate a key pair and provide us with the public key, Akkroo can encrypt the payload before sending it to you. This greatly increases the security of the data if the URL you provided us with is not HTTPS.

To generate a key pair, run the following commands on the command line:

openssl genrsa -out akkrooWebhook.pem 1024
openssl rsa -in akkrooWebhook.pem -pubout -out akkrooWebhook.pub

Send the contents of the .pub file to Akkroo support, along with your hash secret and webhook url. Keep the .pem file secret and use it to decrypt the payload in the webhook.

The payload is encrypted in the following way:

  1. JSON encode the payload resources
  2. Seal the string with OpenSSL envelope encryption, using the public key you provided
  3. Base64 encode the encrypted payload and envelope key

To decrypt the payload, perform these steps in reverse using your private key.