Subscriptions

Lighthouse API use a subscription mechanism to notify 3rd-party within various events which was triggered by our components.

A subscription is a URI which 3rd-party maintain and use to receive events from Lighthouse system. 3rd-party has to authenticate our requests and parse a JSON object.

Authentication (HMAC)

Lighthouse API send's an authentication information in header for each event.

  • x-access-key - 3rd-party client_id, same as used to be authenticated in Lighthouse API
  • x-timestamp - signature generated time in seconds, used to validate a signature.
  • x-signature - generated signature must match a signature generated by 3rd-party ;

This section shows the steps how to validate a request with example Lighthouse credentials.

  • client_id: 23b08412a29bbe8625967e16c1a41dc9
  • client_secret: de17f1f0-4816-157b-97ae-eb4b0f656a1f

Steps to generate a combined string for signature

  1. Use your client_id, etc: 23b08412a29bbe8625967e16c1a41dc9
  2. Use a POST as method for all subscriptions
  3. Extract a subscription path from url, etc: https://demo.shift4payments.com/subscriptions/order it would be /subscriptions/order
  4. Use a received request payload, etc: { "event": {....}, "payload": {....} }
  5. Use a timestamp received in headers, like: 1554456360

Final combined string will look like:

23b08412a29bbe8625967e16c1a41dc9POST/subscriptions/order{ "event": {....}, "payload": {....} }1554456360

Generate a HMAC-SHA256 digest from string to sign with client_secret which is de17f1f0-4816-157b-97ae-eb4b0f656a1f.

Create a signature, encode digest with HEX. For this example signature will be: 0ef94411f7e06fd28906719f3f1366585c50814040fec5f9fe0309a2e83e277b

Subscription Event

POST {third-party-subscription-url}

Request Body (required)

Content-Type: application/json

{
  "event": {
    "component": "online-ordering",
    "resource": "Menu",
    "action": "updated",
    "name": "online-store.Menu.updated",    
    "version": "v1",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "locationId": 1,
  }
}

Event

Name Type Description
component* string Defines a component which has dispatched this event, like: pos, online-ordering
resource* integer Defines a resource which is related to this event, like: Menu
action* string Defines a action which has triggered an event, like: updated
name* string Unique event name (combined component, resource and action), like: online-ordering.Menu.updated
version* string Define a version of this event, like: v1
subscriptionId* string Unique id for subscription managing (coming feature)
dispatchedAt* string Defines when this event has been dispatched

Payload

Subscription payload depends on a specific functionality

results matching ""

    No results matching ""