This page describes the available security measures when using Go1 webhooks.
Introduction
This documentation outlines the security measures available within the Go1 webhook ecosystem. We'll explore three key security options: Authentication, Webhook Signatures, and IP Validation. By implementing these security protocols, you can fortify your webhook endpoints against unauthorized access and malicious activities. These measures ensure the integrity and confidentiality of your data, empowering you to process information from Go1 with confidence.
Authentication
Go1 webhooks allow you to configure authentication with an external system. Currently,
oauth2
authentication with a
client_credentials
grant type is supported.
To enable authentication on your webhook, create or update a webhook, with the
auth_type
field set to
oauth2
, and include your client credentials via the
oauth2
object. See the example request below:
curl
Go1 will then communicate with your authentication server using the configured credentials to generate an oauth2 token, which will be included in an
authorization
header of any webhook event we send. Sample payload including oauth2 token:
json
Go1 will cache your oauth token, and only generate a new token when the current token expires, or is rejected by your endpoint.
Signatures
Go1 can sign the webhook events it sends your endpoint by including a signature, with a secret key phrase determined by you, in each request’s header. This allows you to verify that the event requests were sent by Go1 and not by an unauthorized third party.
Webhook signature setup
In order to activate the signature, create or update a webhook with a
secret_key
(max 64 characters). See the example request below:
curl
Once you’ve done so, all requests made to your webhook endpoint will include a Go1-Signature value in the header. An example payload could look like this:
json
Webhook signature verification
As shown below in the example below, the signature is made up of the component
t
, representing the timestamp when the signature has been created, and the component
v1
, which contains the signature itself.
json
The
t
timestamp can be used to prevent replay attacks, by rejecting requests containing a timestamp which is too far in the past. The signature itself is generated using a hash-based message authentication code (HMAC) with the SHA-265 algorithm.
To verify the signature against your secret key, follow the steps below.
Step 1. Extract the timestamp and signature from the request header
Split the header value of
Go1-Signature
, using the
,
character as the separator, to retrieve an array of components. Then split each component, using the
=
character as the separator, to get a key and value pair. The value for the key
t
corresponds to the timestamp, and
v1
corresponds to the signature.
Step 2. Calculate your own signature
Concatenate the following components to a string:
The timestamp
The
.
character
The JSON payload as a string
Using the example payload you should have string looking like this:
json
Now use the
secret_key
which you have setup for this webhook earlier to compute an HMAC with the SHA256 hash function:
json
Step 3. Compare the received signature with your own
Compare the signature you have received in the request with the expected one which you calculated yourself. If they match, the request and payload come from a sender who knows your
secret_key
.
IP security
The Go1 platform is using the IP range
20.188.251.48/28
(Australia East),
13.67.161.224/28
(Central US) and
13.69.178.32/28
(North EU) for traffic from its Web/API fleet. This whole range is solely allocated to Go1. You can expect connections from webhooks to come from those IPs and allow them.