Webhooks

Webhooks allow your servers to be notified of events happening in NeoDay.

Format

Webhooks are sent as POST requests to a configurable URL. The request body will contain a list of events encoded as a JSON document:

{
    "events": [
        {
            "name": "transaction-created",
            "data": {
                "id": "mj1zlgp714al6iyzhjx5h0rjb",
                "stack_id": "nruy7lwgc1b1xoni7nspt38k1",
                "block_id": "r4ic8l9hp5quijn5j2lhyboy8",
                "user_id": "gylt92r3n6gtrt6ks4y1nxcpk",
                "value": 100
            }
        },
        {
            "name": "survey-answer-submitted",
            "data": {
                "survey_id": "ljul3y5pd82ku200uprz4yau9",
                "question_id": "xleyk5jmrqydg4awbmwom8ie3",
                "answer_id": "jzxdw4m61xl7m5kg2iicc1mcv"
            }
        }
    ]
}

Request verification

The request will contain headers which you must use to verify that the request came from NeoDay:

  • X-NeoDay-Client-ID: Your client ID
  • X-NeoDay-Signature: A HMAC signature of the request payload signed with your client secret
POST /your-webhook-url?locale=en_GB HTTP/1.1
Host: www.acme.com
X-NeoDay-Client-ID: ak5xkfd97p7il0w1xffexye9g
X-NeoDay-Signature: 225e50ff5b0a830b15d9c8c8e6c5f9d15e9ecab0736b5e940e3ddb2bf1308dce
Content-Type: application/json

{
    "events": [
        {
            "name": "transaction-created",
            "data": {
                "id": "mj1zlgp714al6iyzhjx5h0rjb",
                "stack_id": "nruy7lwgc1b1xoni7nspt38k1",
                "block_id": "r4ic8l9hp5quijn5j2lhyboy8",
                "user_id": "gylt92r3n6gtrt6ks4y1nxcpk",
                "value": 100
            }
        },
        {
            "name": "survey-answer-submitted",
            "data": {
                "survey_id": "ljul3y5pd82ku200uprz4yau9",
                "question_id": "xleyk5jmrqydg4awbmwom8ie3",
                "answer_id": "jzxdw4m61xl7m5kg2iicc1mcv"
            }
        }
    ]
}

Creating a webhook

Webhooks can be created via the API. A list of events and your desired url to receive the events on are required. Webhooks are registered under the currently authenticated client. Events sent to the webhook's url will be signed with the secret of the client that created the webhook.

POST /api/1/terminal/webhooks?locale=en_GB HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

{
    "events": ["coupon-slip-claimed-event"],
    "url": "https://example.com/my-coupon-web-hook"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "kzewqyxuj3nlw5x2a18ye4qu4",
    "events": ["coupon-slip-claimed-event"],
    "url": "https://example.com/my-coupon-web-hook",
    "headers": {}
}

Custom headers

Optionally any custom headers you want to be sent to your endpoint can be configured by setting the "headers" property when creating a webhook.

POST /api/1/terminal/webhooks?locale=en_GB HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

{
    "events": ["coupon-slip-claimed-event"],
    "url": "https://example.com/my-coupon-web-hook",
    "headers": {
        "My-Custom-Header": "A value"
    }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "kzewqyxuj3nlw5x2a18ye4qu4",
    "events": ["coupon-slip-claimed-event"],
    "url": "https://example.com/my-coupon-web-hook",
    "headers": {
        "My-Custom-Header": "A value"
    }
}

Both the header key and value must be a string value.

Listing all registered webhooks

You can fetch a list of all of your registered webhooks like so:

GET /api/1/terminal/webhooks?locale=en_GB HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "kzewqyxuj3nlw5x2a18ye4qu4",
        "events": ["coupon-slip-claimed-event"],
        "url": "https://example.com/my-coupon-web-hook",
        "headers": {}
    }
]

Deleting a webhook

To stop receiving events you can delete a webhook:

DELETE /api/1/terminal/webhooks/kzewqyxuj3nlw5x2a18ye4qu4?locale=en_GB HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

Available events

At the moment only a single event is available:

Coupon slip claimed

To receive updates about all coupons being handed out you can create a webhook listening for the coupon-slip-claimed-event event.

The event has the following payload:

{
    "id": "fh7854299qklgjpgx2l9m8xq2",
    "couponId": "ehf5c87wrf3pbpeb0kpbefm6d",
    "userId": "qy6s0a9ybf8au7i9gysw6radr",
    "title": "One free hug",
    "description": "This coupon entitles the bearer to one free hug. Redeemable at any time",
    "image": {
        "type": "image",
        "data": {
            "src": "https://example.com/image.jpg",
            "alt": ""
        }
    },
    "isRead": false,
    "isDeleted": false,
    "ticket": {
        "state": "issued",
        "display": {
            "systemName": "ean13-barcode-ticket-display",
            "title": "Barcode"
        },
        "code": "ABCD-1234-EFGH"
    }
}