You can use webhooks with GoLinks to be notified of events that occur in your GoLinks workspace, such as when a golink is created. To use webhooks, you need to be on the Enterprise plan. You can upgrade to the Enterprise plan by visiting the billing page. If you have any questions about the Enterprise plan, you can reach out to the Sales team.
Set up your endpoint URL
Before you can use webhooks with GoLinks, make sure you have your own endpoint set up to receive notification requests. GoLinks will send POST requests with the webhook data to your endpoint URL. The data will be in JSON format and will contain the Event object that includes the full details of the event.
Once your endpoint URL receives the event, make sure that your endpoint returns a 2XX HTTP status code. Any other status code, except 3XX, will be seen as a failed attempt and the notification request will be resent. After multiple retries, with a maximum of 6 retries, GoLinks will stop resending the notification request.
Subscribe to an event
Sign in to your GoLinks account and go to the Developers tab on the “Settings” page. In the “Webhooks” panel, click on “Manage” and click the “Create endpoint” button.
Enter your endpoint URL, an optional description, and select the event you want to subscribe to in order to receive notification requests. We currently support golink creations. When you are done, click the “Create endpoint” button.
Once created, you will see the following information in the table: the endpoint URL, the person that created the endpoint, the status of the endpoint and the timestamp when the endpoint was created.
Unsubscribe to an event
To unsubscribe from an event, click on the options button (3 dots) for the endpoint URL you want to edit and click the “Edit” button.
To remove an event, simply click the “X” icon for the event you want to remove and click on “Update endpoint”. Now you won’t receive any new notification requests for the event you removed.
You can also disable an endpoint to not receive new notification requests to any of the events the webhook is subscribed to. To do so, click the options button and click the “Disable” button. Once you confirm that you want to disable the endpoint, the status of the event will change to “Disabled”.
You can always re-enable it by clicking the “Enable” button or delete the endpoint by clicking the “Delete” button.
Test the webhook endpoint
After setting up your endpoint to receive notifications and creating the endpoint in GoLinks, you can test out your webhook endpoint. The event object that your endpoint URL receives will contain the following parameters. The dot notation denotes a child attribute.
| Attribute | Type | Description |
|---|---|---|
| event_id | Integer | The unique ID for the event object. |
| webhook_id | Integer | The ID of the webhook that is subscribed to the event. |
| event_type | String | The type of event that occurred (e.g. golink.created). |
| event_data.object | Object | The object that contains the data of the event (e.g. the payload of the newly created golink). |
| attempts | Integer | The current attempt number to notify the endpoint URL of the event (starting at 1). |
| created_at | Integer | The time at which the event object was created. Measured in seconds since the Unix epoch. |
For example, when a user creates a new golink, the following event object will be sent to your endpoint URL:
{
"event_id": 12113,
"webhook_id": 120,
"event_type": "golink.created",
"event_data": {
"object": {
"gid": 12130,
"cid": 12,
"user": {
"uid": 484371,
"first_name": "Test",
"last_name": "User",
"username": "test.user",
"email": "test.user@golinks.io",
"user_image_url": "https://www.gravatar.com/avatar/94d093e..."
},
"url": "https://drive.google.com/drive/",
"name": "drive",
"description": "Company shared Google Drive",
"tags": [
{
"tid": 79,
"name": "drive"
}
],
"unlisted": 0,
"variable_link": 0,
"pinned": 0,
"created_at": 1576577874,
"updated_at": 1601101700
}
},
"attempts": 1,
"created_at": 1576577874
}
You can verify that a request has been sent by checking the attempt logs in the Developers tab under “Webhooks”. The log shows the status of the request, the event type, the number of times GoLinks has sent the event to the endpoint URL and the request and response body.
Verify the request signature
Every webhook event that is sent to your endpoint URL will include the signature header GoLinks-Webhook-Signature. This ensures that the request is coming from GoLinks and avoids a spoofing attack. To verify the signature, you first need the signing secret for the endpoint you created in GoLinks. To obtain the secret, click on the options button for the endpoint you want to view the signing secret for (Note that every endpoint contains a unique secret). A modal will appear and display the signing secret.
GoLinks creates the hashed signature using HMAC with SHA-256. To verify the signature, recalculate the hash value by computing an HMAC with a SHA-256 hash function using the signing secret as the key and the un-parsed JSON request payload as the message. Compare the expected hash signature with the signature of the GoLinks-Webhook-Signature header. If the values match, then the request came from GoLinks. If the values do not match, ignore the request as it may have been tampered with in transit.
Retries
When a 2XX status code is not received from the endpoint URL, GoLinks will attempt to resend the notification requests up to 6 times. If your server doesn’t respond or returns an error on the 6th try, GoLinks will no longer attempt to redeliver the notification request. Note that GoLinks will not retry the request if the returned status code is 410 (access to the target resource is no longer available at the origin server) and the request will be shown as “Failed” in the log.
GoLinks will retry the request in the following cases: a status code that is not 2XX or 3XX is returned, a response is not received at all (connection failure) or a response isn’t received within 4 seconds (request timeout).
