Webhooks

Whenever a new event needs to be delivered to your application, a webhook will be called. For now webhook registration is a manual process, to get started you will need to give the Tyro Connect team your webhook url, and we will load it into the system.

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

id
string

The id of event being delivered.

type
required
string

The type of event being delivered.

required
object
{
  "id": "aaa-bbbcccddd-eee-0000",
  "type": "WOOF",
  "data": {
    "id": "a_uuidog",
    "uri": "https://api.tyro.com/connect/dogs/a_uuidog",
    "resource": "dogs"
  }
}

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 or Unknown Events

Please make sure that your system can handle duplicate events i.e a notification with an identical type and id. If you receive a 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.

Another scenario you need to handle is if 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.

Copyright © Tyro Payments 2019-2021. All right reserved.