Pusher API reference

The Pusher API publishes information to your service. This information is data related to products, purchases, inventory etc.

You can subscribe to specific events in the Pusher API, so that you don't need to poll for data related to the events. When these events occur, the Pusher API will publish information about the events to your service.

Examples of events:

PurchaseCreated is triggered when a purchase gets created.
ProductUpdated is triggered when product information gets updated in the product library. See the list of all supported events.

The Pusher API uses webhooks. Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook, users configure a webhook listener and subscribe it to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages. The messages are triggered when events occur.

Base URL

https://pusher.izettle.com

OAuth Scope

You can create webhook subscriptions using an access token or API key that corresponds to an organization. To update, delete, or view a subscription, use the same access token or API key.

To create or update a subscription to an event, you will need to be authorised with the corresponding scope.

E.g. you will require the READ:PURCHASE scope if you want to subscribe to the PurchaseCreated event. See the list of scopes for supported events.

For more information on how to get authorisation for a particular scope, see OAuth API.

Create a subscription

Creates a webhook subscription to a specific event.

Once the subscription for an event gets created, the Pusher API will publish data on your service whenever that event occurs.

Example: You created a subscription for the ProductUpdated event. Whenever a product gets updated in the product library, the ProductUpdated event occurs. Then you will receive event data on the destination server that you have exposed publicly. The event data is a payload for the updated product. See the list of payloads for all events.

Note: The Pusher API will push data for an event only once. However, there may be cases where it gets published more than once. You don't need to save the data more than once.

1
POST /organizations/{organizationUuid}/subscriptions

See example Create a webhook subscription.

Parameters

Click to hide all request parameters for creating a subscription.

Name	Type	In	Required/Optional	Description
organizationUuid	string	path	required	Unique identifier for your organisation. You can use following options to fill in this value: Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request. Get it by using the `users/self` endpoint of OAuth API. For more information, see OAuth API.
uuid	string	query	required	Unique identifier for the subscription as UUID version 1.
transportName	string	query	required	The message option used by Pusher API. Currently only `WEBHOOK` is supported.
eventNames	array	query	required	Event names for events that you want to create subscription for. The events are specified in an array. If you pass an empty array, you will subscribe to all events that the Pusher API supports. In this case, make sure that you have all the corresponding authorisation scopes issued. See the list of scopes.
destination	string	query	required	Your service URL publicly exposed where the Pusher API will publish messages for subscribed events.
contactEmail	string	query	required	The email address used to notify in case of any errors in subscription or the destination. The email must be a valid email address and should not exceed 512 characters.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when a subscription is successfully created.
401 Unauthorized	Returned when one of the following occurs: The authentication information is missing in the request. The authentication token has expired. The authentication token is invalid.
403 Forbidden	Returned when the scope being used in the request is incorrect. E.g. If you provide a permission scope of `READ:PRODUCT` while creating a subscription for `PurchaseCreated` then the Pusher API will return 403 in the response.
400 Bad Request	Returned when one of the following occurs: The `transportName` or `uuid` is missing in the request. A subscription with the `uuid` passed in request already exists. The `destination` is not accessible.
422 Unprocessable Entity	Returned when one of the following occurs: The `destination` or `contactEmail` is missing in the request. The `contactEmail` has an invalid value for email address.
500 Internal Server Error	Returned when one of the following occurs: The `destination` responded with a non-successful HTTP response code. The Pusher API encountered an internal server error.

Click to hide response attributes.

A successful 200 OK response will have the following attributes:

Name	Type	Description
uuid	string	Unique identifier for the created subscription as UUID version 1.
transportName	string	The message option used by Pusher API. Currently only `WEBHOOK` is supported.
eventNames	array	The event names for the created subscription.
updated	string	The timestamp (in UTC) when the subscription was last updated.
destination	string	The public URL exposed by you where the Pusher API will publish messages for subscribed events.
contactEmail	string	The email used to notify any errors for subscriptions or the destination.
status	string	The status of the created subscription.
signingKey	string	The key used to verify that all incoming webhook messages from the Pusher API originate from Zettle.

Get all subscriptions

Gets all the webhook subscriptions for an organisation.

1
GET /organizations/{organizationUuid}/subscriptions

See example Get webhook subscriptions.

Parameters

Click to hide all request parameters for getting all subscriptions.

Name	Type	In	Required/Optional	Description
organizationUuid	string	path	required	Unique identifier for your organisation. You can use following options to fill in this value: Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request. Get it by using the `users/self` endpoint of OAuth API. For more information, see OAuth API.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the Pusher API returns a collection of subscriptions for the client.
401 Unauthorized	Returned when one of the following occurs: The authentication information is missing in the request. The authentication token has expired. The authentication token is invalid.
500 Internal Server Error	Returned when the Pusher API encounters an internal server error.

Click to hide response attributes.

A successful 200 OK response will return an array of subscriptions. Each subscription contains the following response attributes:

Name	Type	Description
uuid	string	Unique identifier for the created subscription as UUID version 1.
transportName	string	The message option used by Pusher API. Currently only `WEBHOOK` is supported.
eventNames	array	All the events for the created subscription.
updated	string	The timestamp (in UTC) when the subscription was last updated.
destination	string	The destination URL where the Pusher API will push messages for subscribed events.
contactEmail	string	The email used to notify any errors for subscriptions or the destination.
status	string	The status of the created subscription.
signingKey	string	The key used to verify that all incoming messages from the Pusher API originate from Zettle.

Update a subscription

Updates an existing webhook subscription.

1
PUT /organizations/{organizationUuid}/subscriptions/{subscriptionUuid}

See example Update a webhook subscription.

Parameters

Click to hide all request parameters for updating a subscription.

Name	Type	In	Required/Optional	Description
organizationUuid	string	path	required	Unique identifier for your organisation. You can use following options to fill in this value: Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request. Get it by using the `users/self` endpoint of OAuth API. For more information, see OAuth API.
subscriptionUuid	string	path	required	Unique identifier for an existing subscription as UUID version 1.
transportName	string	query	optional	The message option used by the Pusher API. E.g. `WEBHOOK`. You need to specify the same option that you used while creating the subscription.
eventNames	array	query	optional	Events that you want to update on the existing subscription. The events are specified in an array.
destination	string	query	optional	The destination URL where the Pusher API will push data for the updated subscription.
contactEmail	string	query	optional	The email address used to notify in case of any errors in subscription or the destination. The email must be a valid email address and should not exceed 512 characters.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the Pusher API updates the subscription successfully.
401 Unauthorized	Returned when one of the following occurs: The authentication information is missing in the request. The authentication token has expired. The authentication token is invalid.
404 Not Found	Returned when the subscription to be updated does not exist or cannot be found.
405 Method Not Allowed	Returned when the `subscriptionUuid` is missing in the request.
400 Bad Request	Returned when the `eventNames` parameter contains events that are not supported by the Pusher API.
422 Unprocessable Entity	Returned when one of the following occurs: Returned if the `destination` specified in the request is empty. The `destination` value is not a valid HTTPS URL.
500 Internal Server Error	Returned when the Pusher API encounters an internal server error. In case this error persists, contact our developer support.

Click to hide response attributes.

The Pusher API returns a 200 OK response without any content.

Delete a subscription

Deletes an existing webhook subscription.

1
DELETE /organizations/{organizationUuid}/subscriptions/{subscriptionUuid}

See example Delete a webhook subscription.

Parameters

Click to hide all request parameters for deleting a subscription.

Name	Type	In	Required/Optional	Description
organizationUuid	string	path	required	Unique identifier for your organisation. You can use following options to fill in this value: Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request. Get it by using the `users/self` endpoint of OAuth API. For more information, see OAuth API.
subscriptionUuid	string	path	required	Unique identifier for an existing subscription as UUID version 1.

Responses

Click to hide HTTP status codes.

Status code	Description
204 No Content	Returned when the Pusher API deletes the subscription successfully.
401 Unauthorized	Returned when one of the following occurs: The authentication information is missing in the request. The authentication token has expired. The authentication token is invalid.
404 Not Found	Returned when one of the following occurs: The `subscriptionUuid` is missing in the request. A subscription was not found for the `subscriptionUuid` passed in the request
500 Internal Server Error	Returned when the Pusher API encounters an internal server error.

Click to hide response attributes.

The Pusher API returns a 204 No Content response without any content.

Supported events

Click to hide a list all the events supported by the Pusher API and their corresponding authorization scopes.

Event name	Required scope	Trigger
PurchaseCreated	READ:PURCHASE	A purchase is finalized and a receipt is created.
OrganizationUpdated	READ:USERINFO	A property of an organization is updated. E.g. name, email address etc.
ProductCreated	READ:PRODUCT	A product gets created in the product library.
ProductUpdated	READ:PRODUCT	A product gets updated in the product library.
ProductDeleted	READ:PRODUCT	A product gets deleted in the product library.
InventoryBalanceChanged	READ:PRODUCT	Either: A sale is made for a product and purchase gets created. This leads to change in the balance of the product in the inventory. The stock of a product gets updated in the product library.
InventoryTrackingStarted	READ:PRODUCT	Inventory tracking for a product is enabled in the Zettle Go app.
InventoryTrackingStopped	READ:PRODUCT	Inventory tracking for a product is disabled in the Zettle Go app.
ApplicationConnectionRemoved	any scope	The application was disconnected from Zettle organization and the OAuth refresh token has been invalidated.
PersonalAssertionDeleted	any scope	The API key used to create subscriptions is deleted.

Examples

Create a webhook subscription

Request

1
POST /organizations/{organizationUuid}/subscriptions

1
{
2
    "uuid": "f02f80f8-8f35-11eb-8dcd-0242ac130003",
3
    "transportName": "WEBHOOK",
4
    "eventNames": ["ProductUpdated"],
5
    "destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
6
    "contactEmail": "your_email@domain.com"
7
}

Response

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
}

Get webhook subscriptions

Request

1
GET /organizations/self/subscriptions

Response

1
[
2
    {
3
        "uuid": "f02f80f8-8f35-11eb-8dcd-0242ac130003",
4
        "transportName": "WEBHOOK",
5
        "eventNames": ["ProductUpdated"],
6
        "updated": "2021-03-30T07:48:52.228Z",
7
        "destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
8
        "contactEmail": "your_email@domain.com",
9
        "status": "ACTIVE",
10
        "signingKey": "U0Ani1WTTwwbjUnHlQAEDCRXQoQn9z9e4q55UUTyeZJt89z9XXN5ssd4Cgh0evJa"
11
    },
12
    {
13
        "uuid": "6eefcb26-912c-11eb-a8b3-0242ac130003",
14
        "transportName": "WEBHOOK",
15
        "eventNames": ["ProductDeleted"],
16
        "updated": "2021-03-30T07:49:35.294Z",
17
        "destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
18
        "contactEmail": "your_email@domain.com",
19
        "status": "ACTIVE",
20
        "signingKey": "PSjClzC2HNEZZoFU7aaF9DSmn9WJBXLfEIAkbBq15lNknnijPT2AKEsvf2YHPrsQ"
21
    },
22
    {
23
        "uuid": "7c9e43ce-912c-11eb-a8b3-0242ac130003",
24
        "transportName": "WEBHOOK",
25
        "eventNames": ["InventoryBalanceChanged", "ProductCreated"],
26
        "updated": "2021-03-30T07:50:13.489Z",
27
        "destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
28
        "contactEmail": "your_email@domain.com",
29
        "status": "ACTIVE",
30
        "signingKey": "H2XDdE5REqT55rDTvAPqpA8UDY4mO3QSmcLO7h0PxvJ4qETKfx9rfzVxuKplUOYz"
31
    },
32
    {
33
        "uuid": "08db4d6e-912d-11eb-a8b3-0242ac130003",
34
        "transportName": "WEBHOOK",
35
        "eventNames": ["InventoryBalanceChanged", "ProductCreated"],
36
        "updated": "2021-03-30T07:54:11.798Z",
37
        "destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
38
        "contactEmail": "your_email@domain.com",
39
        "status": "ACTIVE",
40
        "signingKey": "s4T28XWVGBl8us8fvRxmY4HnFQgTbMiFtqniXpWrAIx0rv5YN7RFAygyjWSg7Nip"
41
    }
42
]

Update a webhook subscription

Request

1
PUT /organizations/self/subscriptions/df209936-8f31-11eb-8dcd-0242ac130003

1
{
2
    "eventNames": ["ProductUpdated", "CardPaymentInvalid"]
3
}

Response

1
200 OK

Delete a webhook subscription

Request

1
DELETE /organizations/self/subscriptions/uuid/f02f80f8-8f35-11eb-8dcd-0242ac130003

Pusher API reference

Base URL

OAuth Scope

Create a subscription

Parameters

Responses

Get all subscriptions

Parameters

Responses

Update a subscription

Parameters

Responses

Delete a subscription

Parameters

Responses

Supported events

Examples

Create a webhook subscription

Get webhook subscriptions

Update a webhook subscription

Delete a webhook subscription

Related information