Webhooks: technical guide

You typically need a server to receive webhooks events. When you add a webhook, you specify a URL where you want to receive the webhook events. The system sends a HTTP POST payload to this URL when events occur.

When your server receives a webhook event, it can process and respond to the webhook. For example, code running on your server could update an external issue tracker, trigger CI builds, update a backup mirror, or deploy to a production server when it receives a webhook event.

Create a new endpoint

A webhook is an endpoint on your server that receives requests notifying you about events. Add a new endpoint to your server and make sure it’s publicly accessible so we can send authenticated POST requests to you.

How to create a new endpoint on your server

For the purposes of testing, you can use a local server to receive webhook events from Akoya.

First, you need to expose your local development environment to the internet so Akoya can deliver events. You can use ngrok to do this. ngrok is available, free of charge, for all major operating systems. For more information, see the ngrok download page.

After installing ngrok, you can expose your localhost by running ./ngrok http 4567 on the command line. 4567 is the port number on which our server will listen for messages. You should see a line that looks something like this:

Forwarding  <http://7e9ea9dc.ngrok.io> -> 127.0.0.1:4567

Make a note of the *.ngrok.io URL. You’ll use it to set up your webhook.

Frequently asked questions

Q: What will happen if we respond with a non-200 HTTP response?

A: Our systems keep a record of all webhook delivery and are informed when there is an unsuccessful event. We will try to send the webhook 3 times.

Q: What if we fail to receive your webhook?

A: Please test the connectivity between your webhook server and Akoya. If there are no issues, please log into the Data Recipient Hub and submit a support ticket so we can assist you in troubleshooting the problem.

Q: What if we fail a lot of requests? will our subscription be revoked/paused?

A: Webhook failures will not change the status of your subscription.

Change log