PassSlot Logo

Webhooks
Use webhooks to be notified about events that happen to your passes

Interacting with third party APIs like PassSlot often suffers from two important problems:

  • Services not directly responsible for making an API request may still need to know about it.
    Think of your app creating Wallet passes and your backend that wants to know about it
  • Some events, like downloading a Wallet pass by the user, are not the result of a direct API request

Webhooks solve these problems by letting you register a URL that PassSlot will POST anytime an event happens to your Wallet passes. When the event occurs, for example when a pass is added to Apple Wallet (Wallet), PassSlot creates an event object. This object contains all the relevant information, including the type of event and the data associated with that event. PassSlot then sends an HTTP POST request with the event object to any URLs in your account's webhooks section. You can find a full list of all event types in the events docs.

Configuring your webhooks

Webhooks can be configured in the webhooks section of the PassSlot dashboard. Clicking the add button to reveal a form to add a new URL for receiving webhooks.
You can enter any URL you'd like to have receive the events and you can add as many URLs as you like. For every webhook you create, a dedicated secret will be generated which you can use to verify the origin of the events.

Verification of your webhook

Before you can enable your webhook, we first need to verify your webhook URL. For this we are sending an webhook.verify event to your URL (see the example below). For successful verification you need to return this token in the response to the event. 

{
   "id":"2150c68e-4075-4a26-8690-1579deb08a27",
   "type":"webhook.verify",
   "created":"2014-03-15T20:12:59Z",
   "data":{
      "token":"RBqXiclacPSqRsRfQAXRSdNmqCLwbpdM"
   }
}

Receiving a webhook

Configuring your backend to receive a webhook is as easy as providing a publicly available URL that PassSlot can call. With PHP, you might create a new .php file on your server; with a framework like ruby on rails, you would add a new route with the desired URL.

Webhook data is sent as JSON in the request's body. The full event details are included and can be used directly. Further the event is digitally signed so that you can verify that the event did came from PassSlot. The JSON body is signed with HMAC-SHA1 using the secret you can find in the webhooks section. The signature is added as a HTTP header named X-Passslot-Signature.

Here is an example of how such a call looks like:

POST /webhook HTTP/1.1
X-Passslot-Signature: sha1=3ff90085966eceb526a912c3db1b882dbe81fe33
X-Passslot: event
Host: yourbackend.com
Content-Type: application/json
Content-Length: 204
Connection: keep-alive
Accept: application/json

{"id":"1c9497e1-de5e-4256-86e5-3a95de5f881f","type":"pass.created","created":"2012-11-25T17:07:24Z","data":{"serialNumber":"da1c8782-76ae-4092-9122-a4a44cc6e561","passTypeIdentifier":"pass.example.id1"}}

Responding to a webhook

To acknowledge that you received the webhook your server should return a 200 HTTP status code. Any other information you return in the request will be ignored. Any response code outside the range 200-299 will indicate that you did not receive the webhook and our service retires to developer the webhook until it succeeds. Oury system gradually reduces the retry rate to avoid flooding your endpoint with too many requests

Ready to start?

Events / Webhooks