How to set up webhooks with GoLinks

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.

Empty webhooks table

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.

Create endpoint modal

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. 

Edit option for editing a webhook endpoint

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.

Edit webhook endpoint modal

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”.

Disabled webhook endpoint

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.

AttributeTypeDescription
event_idIntegerThe unique ID for the event object.
webhook_idIntegerThe ID of the webhook that is subscribed to the event.
event_typeStringThe type of event that occurred (e.g. golink.created).
event_data.objectObjectThe object that contains the data of the event (e.g. the payload of the newly created golink).
attemptsIntegerThe current attempt number to notify the endpoint URL of the event (starting at 1). 
created_atIntegerThe 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.  

Webhook attempts log

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. 

View signing secret option for a webhook endpoint

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).

Was this helpful?

Thanks for your feedback!

Need more help?

Technical support

Send us your technical inquiries

Contact us →
Contact sales

Demo or answer sales questions

Contact sales →
Chat with us

Get quicker responses with chat

Chat now →
Blog

GoLinks and productivity articles

View blog →

Purpose-built solutions that deliver
information to your fingertips

Golinks logo
Golinks section
Memorable short links

Get to any resource instantly using memorable go links shared by your entire org.

⚡ Instant resource access
🧠️ Intuitive knowledge sharing
💡 Information discovery
✨ AI-powered suggestions
Gosearch logo
Gosearch section
Enterprise search

Search across all your content hubs from one search bar—results powered by generative AI.

🔍️ Search across all work apps
✨ AI-powered results
🤖 AI conversational chat
⚡️ 100+ data connectors
Goprofiles logo
Goprofiles section
People knowledge

Find and discover information about the people of your org. Give recognition and celebrate achievements.

🙋‍♀️️ Employee profiles
👍️ Peer recognition
📈️ Employee engagement
✨ AI-powered search