Enhance Zealy's Capabilities with Webhook Connections.



Zealy provides webhooks which allow you to receive HTTP push notifications whenever data is created or updated. This allows you to build integrations on top of Zealy. You could trigger CI builds, perform calculations on quest data, or send messages on specific conditions – you name it.

Please visit Settings > Integrations > Zapier & Webhooks to set up your webhooks.

How does a Webhook work?

A Webhook push is simply a HTTP POST request, sent to the URL of your choosing. The push is automatically triggered by Linear when data updates. For an example of what data a payload contains, see The Webhook Payload.

Your webhook consumer is a simple HTTP endpoint. It must satisfy the following conditions:

  • It's available in a publicly accessible HTTPS, non-localhost URL
  • It will respond to the Zealy Webhook push (HTTP POST request) with an HTTP 200 ("OK") response

If a delivery fails (i.e. server unavailable, response took longer than 5 seconds, response body was bigger than 5000 bytes or responded with a non-200 HTTP status code), the push will be retried 15 times. Here an exponential backoff delay is used: the attempt will be retried after approximately 10 minutes, then 30 minutes, and so on. If the webhook URL continues to be unresponsive the webhook might be disabled by Zealy, and must be re-enabled again manually.

To make sure a Webhook POST is truly created by Zealy, we generate a random secret that will be attached to the body of the request in the secret field.

For additional information on Webhooks, there are several good resources:

What can I use it for?

  • Integrate with Zapier
  • Automate custom rewards
  • Announce new quests on Telegram

And much much more!

Getting started with Zealy Webhooks

  1. Identify which events you want to monitor.
  2. Develop a webhook endpoint function to receive event data POST requests.
  3. Register your endpoint within Zealy using the Webhooks Dashboard in Settings > Integrations > Zapier & Webhooks.
  4. Secure your webhook endpoint.

Creating a simple Webhook consumer

You might consider using something like Netlify Functions, which provides a straightforward way of deploying simple HTTP(S) endpoints:

// server.js
// Use this sample code to handle webhook events in your integration.
// 1) Paste this code into a new file (server.js)
// 2) Install dependencies
//   npm install express
// 3) Run the server on http://localhost:4242
//   node server.js
// The library needs to be configured with your account's secret key.
// Ensure the key is kept out of any version control system you might be using.
const express = require('express');
const app = express();
// This is your Zealy webhook secret for testing your endpoint locally.
const endpointSecret = '5888a6800dbac634e52d8504f097e064';'/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  const payload = req.body;
  // Does createdAt make more sense than time?
  const { id, type, data, time, secret } = payload;
  if (secret === endpointSecret) {
    // Do something neat with the data received!
  // Return a 200 response to acknowledge receipt of the event
app.listen(4242, () => console.log('Running on port 4242'));

Configuring in settings

Set up the webhook and the events it should monitor in Settings > Integrations > Webhooks.

The Webhook payload

The webhook HTTP payload will include information both in its HTTP headers and its request body.

The payload will be sent with the following HTTP headers:

User-Agent: Zealy-Webhook
Content-Type: application/json; charset=utf-8
  id: string // unique ID for this event (UUID v4)
  data: EventData, // event data, see below
  time: number, // timestamp, in milliseconds
  secret: string, // secret generated when you created your webhook, used for checking origin

EventData field per event:

type JoinedCommunityEventData = {
  community: WebhookCommunityPayload;
  user: WebhookUserPayload;
type LeftCommunityEventData = {
  community: WebhookCommunityPayload;
  user: WebhookUserPayload;
type QuestSucceededEventData = {
  community: WebhookCommunityPayload;
  user: WebhookUserPayload;
  quest: WebhookQuestPayload;
  taskInputs?: Array<{
    taskId: string, // task ID (uuid v4)
    taskType: 'number' | 'date' | 'api' | 'text' | 'discord' | 'url' | 'telegram' | 'quiz' | 'invites' | 'visitLink' | 'file' | 'poll' | 'opinion' | 'twitterFollow' | 'twitterSpace' | 'tweetReact' | 'tweet',
    input: WebhookQuestTaskInputPayload,
type SprintStartedEventData = {
  community: WebhookCommunityPayload;
  sprint: WebhookSprintPayload;
type SprintEndedEventData = {
  community: WebhookCommunityPayload;
  sprint: WebhookSprintPayload;

Common entities:

type WebhookCommunityPayload = {
  id: string; // community ID (uuid V4)
  name: string; // community name
  subdomain: string; // community subdomain
  blockchain: string;
  discord: string | null; // discord URI of the community, e.g.,
  twitter: string | null; // twitter handle of the community, e.g., zealy_io
  website: string | null; // website URI of the community
type WebhookUserPayload = {
  id: string; // user ID (uuid V4)
  name: string | null; // user display name
  twitter: {
    id: string; // user twitter ID
    username: string | null; // user twitter handle
  } | null;
  discord: {
    id: string; // user discord ID
    handle: string | null; // user discord handle
  } | null;
  email: string | null; // user email
  addresses: Dict<string>; // key/value dictionary for wallets
type WebhookQuestPayload = {
  id: string; // quest ID (uuid V4)
  name: string; // quest display name
  categoryId: string; // category ID (uuid V4)
  categoryName: string | null; // category display name
  xp: number | null; // XP reward
  published: boolean | null; // true if quest is published, false otherwise
  autoValidate: boolean | null; // true if quest is autovalidated, false otherwise
type WebhookQuestTaskInputPayload =
 | { } // for task type 'visitLink', 'invites', 'discord', 'telegram', 'twitterFollow', 'twitterSpace', 'api'
 | { value: string } // for task type 'text', 'date', 'url', 'opinion'
 | { value: number } // for task type 'number'
 | { values: string[] } // for task type 'poll', 'quiz'
 | { fileUrls: string[] } // for task type 'fileUrls'
 | { tweetId?: string } // for task type 'tweetReact', 'tweet'
type WebhookSprintPayload = {
  id: string; // sprint ID (uuid V4)
  startingAt: ISOString; // sprint starting date -
  endingAt: ISOString; // sprint ending date

Securing webhooks

Creating a webhook will create a random secret that you can use to verify that the request is coming from Zealy webhooks. Copy the secret in the top right of the webhook inspect panel and verify that the secret set in the body of the POST request is the same.

In case the secret is leaked, you can regenerate it from the same page.

CleanShot 2024-01-12 at 16.53.32@2x.png

Testing webhooks

From the webhook’s inspect panel you can manually trigger a test event. Click the button in the top right and select ‘Send test event’. You will be able to select an event type among the monitored event types. An event will be triggered with mock data and the status displayed.


You can see the logs of all past events triggered by the webhook if you click the webhook from the Webhooks page. Filtering by the status you can use the logs to debug if something went wrong. For each event, you can see the error message received and the request that was sent.

You can also retry any event from this page.

CleanShot 2024-01-12 at 16.51.27@2x.png

Integration with Domino

Domino is the Web3 Zapier. It allows you to extend the capabilities of Zealy and automatically review tasks that are not natively supported, such as:

  • Checking if a user's Twitter name or bio contains a specific word
  • Checking a user's NFT & token balance
  • Verifying that a user has invited a certain number of people on Discord
  • And many more

Check out their documentation for integration.

Integration with Zapier

Using our integration with Zapier, you can connect your Zealy community to your Zapier account to unlock powerful workflows and automations with the thousands of apps on Zapier’s platform.

Zapier allows you to connect your Zealy webhooks to several apps and services. To integrate with Zapier:

  1. Create a Zapier account and log in.
  2. In your Zapier dashboard, choose to 'Make a Zap'.
  3. For the trigger, select 'Webhooks by Zapier' and choose 'Catch Hook'.
  4. Enter the custom Webhook URL provided by Zapier into your Zealy webhook configuration.
  5. Customize the action in Zapier to define what happens when the webhook is triggered. This could be updating a spreadsheet, emailing, or any action supported by Zapier's vast app ecosystem.


Was this helpful?