Webhooks

Hark receives events from the outside world in two different ways depending on the integration. GitHub pushes events to a webhook. Gmail does not; it is polled instead. This article covers both, since "why isn't Gmail a webhook" is a fair question once you have read the GitHub side.

GitHub webhook

One endpoint handles every inbound GitHub event for every connected organization:

POST /api/integrations/github/webhook

This single endpoint does two jobs, depending on the event type:

1. Support inbound. An issues or issue_comment event on a connected repository becomes a Hark conversation and message, so a GitHub issue can be worked like any other support conversation.
2. Live development sync. push, pull_request, and create (branch) events that mention a work item key (for example ENG-12) become development events on that item. installation and installation_repositories events keep the App's repository list in sync automatically.

Handled event types

Any other event type, or a repository the webhook cannot map to a connected organization, is acknowledged with a 200 and otherwise ignored. This is deliberate: GitHub retries deliveries that fail or time out, so events Hark intentionally does not act on are still ACKed rather than left to retry forever.

Verifying the signature

Every delivery must carry a valid X-Hub-Signature-256 header, or the endpoint returns 401 before it parses anything. The header is checked against an HMAC-SHA256 of the raw request body, keyed with your GITHUB_WEBHOOK_SECRET, using a timing-safe comparison:

expected = "sha256=" + hex(HMAC_SHA256(GITHUB_WEBHOOK_SECRET, rawRequestBody))

If you are building or debugging anything that calls this endpoint directly (rather than letting GitHub deliver to it), you must compute this signature the same way GitHub does, over the exact raw bytes of the body, before the JSON is parsed. Signing the parsed-and-reserialized object will not match, since re-serialization can change whitespace and key order.

const { createHmac } = require('crypto')

function githubSignature(secret, rawBody) {
  return 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
}

Setup

The webhook secret is configured once, in your GitHub App's settings and as the GITHUB_WEBHOOK_SECRET environment variable on your Hark deployment. Both sides must use the same value or every delivery is rejected. Which repositories deliver to this endpoint is controlled by the GitHub App's installation, not by anything in Hark's own UI.

Gmail: polled, not a webhook

Gmail inbound is intentionally different. There is no Gmail webhook endpoint. Instead, a background worker job runs a repeatable poll that syncs new mail for each connected organization, and the same sync logic is available on demand through a manual "Sync now" action. Both paths call the identical underlying sync function, so there is exactly one code path for turning Gmail messages into conversations, whether it runs on its own schedule or because someone asked for a manual refresh.

If you are integrating your own inbound channel and are deciding between a push (webhook) or pull (poll) model, GitHub's webhook is the pattern to follow when the source can reliably deliver signed, retried events to a public endpoint. Polling suits sources (like Gmail) where push delivery would need broader, longer-lived permissions than a periodic pull.