Webhooks

Whenever a new event needs to be delivered to a POS Cloud, a webhook will be called. During the Alpha pilot webhook registration will be a manual process. You will need to give the Tyro Connect team your url and we will load it into the system.

The payload for each event will be an object with the following attributes:

type

required

string

The type of event being delivered.

required

object

id required	string The unique identifier for the `resource`.
uri required	string The full path to the resource.
resource required	string This is the name of the API resource relevant to the event.

Copy

Copied

{
  "type": "ORDER_CREATED",
  "data": {
    "resource": "order",
    "id": "abcxyz123-2c32-4a0d-a0dd-f766e965235e",
    "uri": "https://api.tyro.com/connect/orders/abcxyz123-2c32-4a0d-a0dd-f766e965235e"
  }
}

Response

To indicate that delivery of the notification was successful please return a 200 HTTP response code. A 500 HTTP response code should be returned if the notification could not be processed, if this happens Tyro Connect will retry sending the event 3 times.

Duplicate, Unknown or Out of Order Events

Please ensure your implementation ignores the following occurrences:

Duplicate Events: Please make sure that your system can handle duplicate events i.e a notification with an identical type and id. If you receive an notification about an event you have already received please ignore it. This should be an uncommon occurrence but can occur if Tyro Connect encounters an error and we are not sure we delivered the message to you.
Out of Order Events: Rare network issues could potentially result in out-of-order events. If you receive a notification about an event that appears to be outdated, please ignore it as this is most likely an out-of-order event.
Unknown Events: It is also possible that Tyro Connect publishes events with a type that you do not support. When this happens please ensure that your implementation ignores the event.

Validation

`Tyro-Connect-Signature` Header

Tyro Connect generates a signature for each webhook notification that it sends and the signature is then included in the request as a custom HTTP header Tyro-Connect-Signature.

Signing Key (Pre-Shared Secret)

During setup Tyro Connect will generate signing keys for each of your webhook url's. Different keys can be generated for each event type or we can produce a single key for all events. This signing key is how you can verify that the events were sent by Tyro Connect.

Signature Calculation

To generate a matching signature you must get the http request body as a string and compute a SHA-256 hash of the request body. This hash can then be compared to the Tyro-Connect-Signature header. Here is a pseudocode example:

calculatedSignature = hmacSha256(signingKey, request.body) expectedSignature = request.headers["Tyro-Connect-Signature"]

Signature Comparison

Perform an equality comparison on the expected signature in the header to the calculated signature. If the signatures match you can trust that it was Tyro Connect that sent you the request.