This guide is designed to walk you through the process of setting up webhooks, from environment preparation to verification of successful event capturing.

​
Prerequisites

Before diving into webhook configuration, ensure you have completed the necessary preliminary steps outlined in our Quickstart Guide. This guide will assist you in setting up a new organization and installing the Turnkey CLI. Note: We’ll create a new API Key for testing webhooks below.

​
Environment Setup

Begin by setting the necessary environment variables:

ORGANIZATION_ID=<your-organization-id>KEY_NAME=webhook-test

​
API Key Generation

Generate an new API key using the Turnkey CLI with the following command:

turnkey generate api-key --organization $ORGANIZATION_ID --key-name $KEY_NAME

​
Ngrok Installation and Setup

Ngrok is a handy tool that allows you to expose your local server to the internet. Follow these steps to set it up:

1

Download Ngrok from their website.

2

Follow the provided instructions to install Ngrok and configure your auth token.

​
Local Server Setup

Open a new terminal window and set up a local server to listen for incoming webhook events:

nc -l 8000

​
Ngrok Tunneling

In another terminal, initiate Ngrok to forward HTTP requests to your local server:

ngrok http 8000

Here’s an output of the above command:

Session Status                online
Account                       Satoshi Nakamoto (Plan: Free)
Update                        update available (version 3.7.0, Ctrl-U to update)
Version                       3.6.0
Region                        United States (us)
Latency                       22ms
Web Interface                 http://127.0.0.1:4041
Forwarding                    https://04b2-121-74-183-35.ngrok-free.app -> http://localhost:8000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Save the ngrok URL as an environment variable:

WEBHOOK_URL=https://04•••35.ngrok-free.app # Replace with the URL provided by ngrok

​
Verifying Ngrok Setup

To ensure Ngrok is correctly forwarding requests, perform a test using curl:

curl -X POST $WEBHOOK_URL -d "{}"

Example output:

POST / HTTP/1.1
Host:04b2-121-74-183-35.ngrok-free.app
User-Agent: curl/8.4.0
Content-Length: 2
Accept: */*
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: 195.88.127.47
X-Forwarded-Host: 04b2-121-74-183-35.ngrok-free.app
X-Forwarded-Proto: https
Accept-Encoding: gzip
{}

After executing this command, you should see the request appear in the terminal where nc is running. Terminate the nc session by pressing CTRL+C and restart it by rerunning the nc command.

​
Configuring the Webhook URL

Set your webhook URL using the Turnkey CLI with the following command:

turnkey request --path /public/v1/submit/set_organization_feature --body '{
  "timestampMs": "'"$(date +%s)"'000",
  "type": "ACTIVITY_TYPE_SET_ORGANIZATION_FEATURE",
  "organizationId": "'"$ORGANIZATION_ID"'",
  "parameters": {
    "name": "FEATURE_NAME_WEBHOOK",
    "value": "'"$WEBHOOK_URL"'"
  }
}' --key-name=$KEY_NAME

​
Testing Your Webhook

Assuming the previous request executed successfully it’s time to test out your webhook! In order to verify that your webhook is correctly configured and receiving data, we can simply execute the previous turnkey request command again which creates a new activity request that will be captured by your webhook. Monitor the terminal with nc running to observe the incoming webhook data.

​
Conclusion

By following these steps, you should now have a functioning webhook setup that captures all activity requests for your organization and its sub-organizations. If you encounter any issues or have feedback about this feature, reach out on slack!