Bessa - Velofood Direct Integration

The Bessa Velofood Integrations consists of two parts.

The Bessa API Webhook, used to notify the Bessa API about new orders
The Velofood Order API, used to fetch the order and notify the Velofood about Order Changes.

Bessa API Webhook

This Webhook is needed to notify our order middleware about new orders or order changes. The Webhook is called by the Velefood API. This is a sample body used.

Route

The following Route is used to notify the Bessa API about a new order or an order change.

Live-Api: https://plugin.meisterwork.at/velofood/notification/
Test-Api: https://stgplugin.meisterwork.at/velofood/notification/

Request Body

The main request body, contains the basic information needed to handle events.

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
`id`	string	false	The Event Id
`type`	string	false	The type of the event, possible types: `order.notification` `courier.notification`
`order`	object	false	The order object.
`created_at`	string	false	The timestamp of the event, `ISO-8601`

Order Body

Name	DataType	Nullable	Description

Name	DataType	Nullable	Description
`id`	string	false	The Order Id, should be unique
`venue_id`	string	false	The Venue Id, where the order originated.
`status`	string	false	The order state. Defined by Velofood.
`resource_url`	string	true	Optional, can be omitted, if set use please a valid uri.

Response Body

Code	Description

Code	Description
200	Success
400	Wrong format, Wrong state, missing fields and so on.
403	Invalid Signature
404	The given `venue_id` was not found.

An Example:

# Real World Example
curl -X "POST" "https://stgplugin.meisterwork.at/velofood/notification/" \
-H 'Api-Signature: 3dea94d5e5f164f3fe5a47cd476ab3f8fcb214030af7b0330a81e94d0bf6d59d' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
  "id": "1234",
  "type": "order.notification",
  "order": {
      "id": "5677",
      "venue_id": "9839",
      "status": "CREATED",
      "resource_url": "https://api.velofood.com/order/5677"
  },
  "created_at": "2023-07-19T18:20:12.378509Z"
}'

Authorization

The notification request is contains a signature, this signature is used to check if the notification is real. The signature is created in following way. The following python code snippet shows how the signature is calculated.

import hmac
from hashlib import sha256

def build_signature(secret, payload):
    """
    This function calculates the signature used to authenticate velofood requests.
    :param secret: the secret to encode the payload, the secret is shared between the velofood api and the bessa api.
    :param payload: the notification body as json string
    """
    signature = hmac.new(
        secret.encode('utf8'),
        msg=payload.encode('utf8'),
        digestmod=sha256,
    ).hexdigest()
    return signature

The following code sample is used to show how a notification request should look like. The request body in following example and the secret 1234 where used to create the signature.

# Example Signature
secret = '1234'
payload = '{"id":"1234","type":"order.notification","order":{"id":"5677","venue_id":"9839","status":"CREATED","resource_url":"https://api.velofood.com/order/5677"},"created_at":"2023-07-19T18:20:12.378509Z"}'

signature = build_signature(secret, payload)

# signature contains the following value
# signature = '3dea94d5e5f164f3fe5a47cd476ab3f8fcb214030af7b0330a81e94d0bf6d59d'