Webhooks

Receive listing events in your application as they happen.

How webhooks work

A webhook connects a bot listing to an HTTP endpoint you control. When a subscribed event occurs, dsc.bot sends an HTTP request to that endpoint. Use webhooks to reward voters, react to new reviews, or mirror management activity into another system.

Each webhook belongs to one listing and can subscribe to any combination of the available events. Create separate webhooks when different services need different event sets or credentials.

Create a webhook

1. Open your bot's management dashboard and choose Integration, then Webhooks.
2. Choose New Webhook and enter a friendly name between 3 and 32 characters.
3. Enter the HTTP or HTTPS URL that should receive events.
4. Select at least one event and, optionally, enter an authorization secret.
5. Choose Create Webhook.

Events

• Vote — sent when a user votes for the listing.
• Review — sent when review activity occurs on the listing.
• Audit log — sent for activity recorded in the listing's management audit log.

You can change the selected events later without replacing the webhook.

Authenticate requests

The optional Secret value is sent unchanged in the Authorization request header. Store an unpredictable value in your server's secret manager and compare the complete header value before processing the body.

const expected = process.env.DSC_WEBHOOK_SECRET;
const authorization = request.headers.get('authorization');

if (!expected || authorization !== expected) {
  return new Response('Unauthorized', { status: 401 });
}

Receive events

Accept the webhook's HTTP request, validate its authorization header, parse the JSON body, and return a successful response promptly. Move slow work to a queue so the endpoint does not wait for downstream APIs or long-running jobs.

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/dsc', (request, response) => {
  if (request.get('authorization') !== process.env.DSC_WEBHOOK_SECRET) {
    response.status(401).send('Unauthorized');
    return;
  }

  const event: unknown = request.body;

  // Validate the event and enqueue application-specific work here.
  console.log(event);

  response.status(202).send('Accepted');
});

app.listen(3000);

Manage webhooks

The Webhooks page lists each webhook's name, endpoint domain, type, and subscribed events. Use search to find a webhook by its name, URL, type, or event. The endpoint and secret are hidden from members who do not have permission to edit webhooks.

Choose the edit action to change the name, URL, secret, or subscribed events. Deleting a webhook stops future deliveries immediately and cannot be undone.

Troubleshooting

• Confirm the endpoint is reachable from the public internet and accepts requests at the exact saved path.
• Check that your receiver reads the complete, case-insensitive Authorization header value.
• Make sure the event is selected on the webhook.
• Return a successful response quickly and inspect your server logs before calling other services.
• Edit the webhook to rotate an exposed secret, then update your receiver at the same time.