Create subscriptions

Subscribe to events to stay updated of activities that happen on your Zettle in real time.

• Make sure that authorisation is set up using Authorisation OAuth API.
• Make sure that you have set up an HTTPS endpoint as the destination URL on your server for receiving event notifications. The endpoint must be publicly accessible and correctly process event payloads. See event payloads.
• Make sure that you understand the events that are supported by the Pusher API. For events that are supported by the Pusher API, see Pusher API reference.

For every subscription, generate a version 1 Universally Unique Identifier (UUID).

Note: One UUID can be used only for one subscription.

1. Generate a version 1 UUID. For example, you can generate a version 1 UUID using UUID Generator.

2. Copy and save the UUID. It will be used for creating a subscription.

Before creating subscriptions to the HTTPS endpoint on your app, test the events to which you want to subscribe.

1. Set up a test environment. For example, you can set up the environment using one of the following approaches:

   • You can use the destination URL that you have set up on your server.
   • If you run a local server, you can make it publicly available using ngrok.
   • If you don't run a local server, you can view all requests online using Webhook.site.

2. Test the events and check the payloads by following Step 3: Create a subscription.

You can subscribe to one or more events in one subscription request.

1. Send a POST request to create subscriptions. In the request body, uuid is the version 1 UUID that you generated in Step 1: Generate a version 1 UUID.

Copy
1
POST /organizations/self/subscriptions

Copy
1
{
2
    "uuid": "<version 1 UUID>",
3
    "transportName": "WEBHOOK",
4
    "eventNames": ["<event names>"],
5
    "destination": "<URL to receive events>",
6
    "contactEmail": "<email to receive notifications>"
7
}

Example: The following example creates a subscription to events ProductCreated and PurchaseCreated.

Copy
1
POST /organizations/self/subscriptions

Copy
1
{
2
    "uuid": "ef64c5e2-4e16-11e8-9c2d-fa7ae01bbebc",
3
    "transportName": "WEBHOOK",
4
    "eventNames": ["ProductCreated", "PurchaseCreated"],
5
    "destination": "https://yoururl.domain",
6
    "contactEmail": "email_if_it_breaks@domain.com"
7
}

2. Check that the response returns with an HTTP status code 200 OK.
   • If yes, the subscription is created successfully.
   • If no, update the POST request according to the error message. For more information on error messages, see HTTP status code.
3. Save the value of signingKey from the response. This is the key used to sign all requests and should be stored so that you can validate the request.

Copy
1
{
2
    "uuid": "f02f80f8-8f35-11eb-8dcd-0242ac130003",
3
    "transportName": "WEBHOOK",
4
    "eventNames": ["ProductUpdated"],
5
    "updated": "2021-03-29T16:31:47.087507Z",
6
    "destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
7
    "contactEmail": "your_email@domain.com",
8
    "status": "ACTIVE",
9
    "signingKey": "zLzClQLQN8yfH8aEjONeXzgJRAHR0zpD7RonFCpizujCUCectBlln0vFArTbLPYa"
10
}

4. If you use the destination URL to receive events for the first time, check that the server receives a test message.

Example: The example shows a test message.

Copy
1
{
2
    "eventName": "TestMessage",
3
    "organizationUuid": "ef64c5e2-4e16-11e8-9c2d-fa7ae01bbebc",
4
    "messageId": "0f674460-fab5-11e7-a310-0002ebd6a43c",
5
    "payload": { "data": "payload" }
6
}

5. Make sure that your destination URL always returns a valid HTTP response, within 10 seconds after receiving the events.

After subscriptions are created, you need to set up a mechanism for verifying that events come from Zettle by checking the signature in the events.

The signature hash is generated as hexdigest using HMAC with SHA-256 as the cryptographic hash function.

To verify that events come from Zettle, calculate a signature and compare it with the value in the HTTP header X-iZettle-Signature of the incoming events.

1. Calculate a signature by concatenating the timestamp and payload of the incoming event .: <timestamp>.<payload> and using the stored signing key that you stored in Step 3: Create a subscription.

   The following examples uses Python, PHP, and Java for calculating a signature.

Copy
1
import hmac import hashlib ... payload_to_sign = '{}.{}'.format(timestamp,
2
    payload) signature = hmac.new(bytes(signing_key), msg = bytes(payload_to_sign),
3
    digestmod = hashlib.sha256).hexdigest()

Copy
1
import hmac import hashlib ... payload_to_sign = '{}.{}'.format(timestamp,
2
    payload) signature = hmac.new(bytes(signing_key, 'UTF-8'), msg = bytes(payload_to_sign,
3
    'UTF-8'), digestmod = hashlib.sha256).hexdigest()

Copy
1
$payloadToSign = stripslashes($timestamp . '.' . $payloadStr); $signature
2
    = hash_hmac('sha256', $payloadToSign, $signingKey);

Copy
1
import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec;
2
    import org.apache.commons.codec.Charsets; import org.apache.commons.codec.binary.Hex;
3

4
    ... String payloadToSign = String.format("%s.%s", timestamp, payload); Mac
5
    hmacSHA256 = Mac.getInstance("HmacSHA256"); hmacSHA256.init(new SecretKeySpec(signingKey.getBytes(Charsets.UTF_8),
6
    "HmacSHA256")); String signature = Hex.encodeHexString(hmacSHA256.doFinal(payloadToSign.getBytes(Charsets.UTF_8)));

2. Compare the newly calculated signature with the value in the HTTP header X-iZettle-Signature and take actions accordingly.

Webhook requests time out 10 seconds after the Pusher API sends the events to the destination URL on your server.

To avoid webhook requests failing, configure your server to handle them as soon as possible. This way, the destination URL can respond to the Pusher API before the timeout occurs. A best practice is to handle webhook requests in the background.

To handle webhook requests in the background:

1. Insert webhooks in a queue.
2. Process the webhooks from the queue in background workers.

Tip: If your server is deployed on a platform as a service (PaaS) like Amazon Web Services, check whether webhooks can queued and processed in the background.

• Delete subscriptions
• Update subscriptions
• View subscriptions
• Pusher API reference