Webhooks

Gigapay uses Webhooks to let you know any time an event happens on your account. Webhooks are completely optional, however they allow you to receive real-time updates on events related to your Gigapay account. We notify on the following events:

• Employee.created

• Employee.notified

• Employee.verified

• Payout.created

• Payout.notified

• Payout.accepted

• Invoice.created

• Invoice.paid

The notifications simply contain the object that triggered the event, as represented in the API. For example, the notification for a Employee.verified event may look as following:

POST https://gigatron.se/webhooks/employees/ HTTP/1.1
Content-Type: application/json
Gigapay-Signature: t=1583327301,v1=ad583e2b2093c8d6fb3b65e04b99fc5988e98c0c312909acad334072da7e99ec
...
​
{"id": "25d2af38-59b9-4f73-9452-51787fed5c84", "name": "Karl \\u00C5hlsson", "cellphone_number": null, "email": [email protected], "metadata": {"user_id": 3}, "created_at": "2019-05-20T15:33:08.974624Z", "verified_at": "2019-05-21T09:13:48.625263Z"}

Gigapay-Signature

The notification is signed used the secret_key set for the Webhook, the signature is included in the notification as a Gigapay-Signature header. This allows you to verify that the events were sent by Gigapay, and not by a third party. The signature consists of two parameters; t, the timestamp of when the notification was sent, v the signature of the current scheme. Currently, the only valid signature scheme is v1 which is the HMAC algorithm as described by RFC 2104 using SHA256 as disgestmod.

To verify signatures using the v1 scheme, extract the timestamp from theGigapay-Signature header, and the JSON-encoded notification from the request body. Join these strings with a period, ., as a separator. Compute an HMAC with the SHA256 hash function using the Webhook’s secret_key as the key. Lastly ensure that the signature in the header and the calculated signature matches. A psuedocode outline would be as follows:

secret_key = '...asId'
t, v1 = parse_signature(request.headers.Gigapay-Signature)
payload = t + '.' + request.body
​
hmac = hmac.new('sha256', secret_key.encode('utf-8'))
hmac.update(payload.encode('utf-8'))
signature = hmac.hexdigest()
​
signature == v1

Note, if you are deserializing the JSON-encoded body you will need to reserialize it back to a string before computing the hash. When doing so take care to ensure that the resulting string has the same format as the original one. Some gotchas are:

• White space after , and :.

• Unicode-encoded characters.

• The timestamps are UTC, ISO 8601.