# Receive and verify webhooks _Category: Guides and recipes_ Build an endpoint that accepts HelpCenter.io webhook deliveries, checks that each one really comes from HelpCenter.io, and handles every change once. This guide builds a complete receiver in Node.js, Python and PHP, and shows how to test it before any real delivery arrives. ## Before you start - **A webhook and its secret.** Register one with `POST /v1/webhooks` and a **Read & write** API key (see [Webhooks](https://developers.helpcenter.io/content/webhooks)). The secret appears only in that response. Keep it on your server, for example in an environment variable named `HELPCENTER_WEBHOOK_SECRET`, and never in code that runs in a browser. - **A public URL.** HelpCenter.io delivers only to public addresses: `localhost` and private network addresses are refused. While you develop, expose your local server through a tunneling tool that gives it a public HTTPS address, and register that address. - **Node.js 18 or later, Python 3.8 or later, or PHP 8 or later.** The receivers below use no packages. ## Step 1: Verify the signature Every delivery carries an `X-HCio-Signature` header: `sha256=` followed by the HMAC-SHA256 of the raw request body, keyed with your webhook's secret, in lowercase hexadecimal. Recompute it and compare: - Use the body exactly as it arrived, before any JSON parsing. Parsing and encoding it again can change the bytes, and then the signature no longer matches. If your framework parses JSON for you, read the raw body instead: `express.raw()` in Express, `request.get_data()` in Flask, `$request->getContent()` in Laravel. - Compare the whole header value, `sha256=` included, in constant time. - Answer `401` when the header is missing or doesn't match, and ignore the delivery. ``` const crypto = require('node:crypto'); const SECRET = process.env.HELPCENTER_WEBHOOK_SECRET; function isValidSignature(rawBody, header) { const expected = Buffer.from( 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex') ); const received = Buffer.from(String(header || '')); return received.length === expected.length && crypto.timingSafeEqual(received, expected); } ``` ``` import hashlib import hmac import os SECRET = os.environ["HELPCENTER_WEBHOOK_SECRET"].encode() def is_valid_signature(raw_body, header): expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected.encode(), (header or "").encode()) ``` ``` $secret = (string) getenv('HELPCENTER_WEBHOOK_SECRET'); $rawBody = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_HCIO_SIGNATURE'] ?? ''; $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret); if ($secret === '' || ! hash_equals($expected, $signature)) { http_response_code(401); exit('Invalid signature'); } ``` ## Step 2: Answer within 10 seconds HelpCenter.io waits 10 seconds for your answer. Answer with a `2xx` status as soon as the delivery is verified, and do the work afterward: the receivers below answer `204`, then hand the event to a background task. A status of `400` or higher, a timeout or a connection error makes HelpCenter.io try again after 10 seconds, 30 seconds, 2 minutes and 5 minutes; after the fifth failed attempt, the delivery is dropped. Don't answer with a redirect: a `3xx` counts as delivered, and the redirect is not followed. ## Step 3: Handle each change once A retry repeats the body and the signature exactly, with a new `X-HCio-Delivery` header, so the same change can reach you twice. Keep the signatures of the deliveries you have handled, and answer `204` without doing the work again when one comes back. Keep them longer than retries last: the last one comes about 8 minutes after the first attempt. Deliveries can also arrive out of order. Before you apply a change, compare `data.updated_at` with the value you stored, or fetch the current state from the API: a delivery carries IDs and a few fields, not the article's text, so fetch the article with the [Articles](https://developers.helpcenter.io/content/articles-api) endpoints when you need its content. After `article.deleted`, the article is in the Trash, or deleted for good, and the API answers `404` for it. ## Step 4: Run the receiver Each program verifies the signature, answers `204`, skips repeated deliveries and prints every event. Replace the `console.log`, `print` or `error_log` calls with your own work. The list of deliveries already handled lives in memory (or in temporary files in PHP): use your database in production. ``` // server.js: receive HelpCenter.io webhooks (Node.js 18+, no dependencies) const http = require('node:http'); const crypto = require('node:crypto'); const SECRET = process.env.HELPCENTER_WEBHOOK_SECRET; const PORT = Number(process.env.PORT || 3000); const seen = new Set(); // Deliveries already handled. Use your database in production. function isValidSignature(rawBody, header) { const expected = Buffer.from( 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex') ); const received = Buffer.from(String(header || '')); return received.length === expected.length && crypto.timingSafeEqual(received, expected); } function handleEvent(payload) { const { event, data } = payload; if (event.startsWith('article.')) { console.log(`${event}: article ${data.id} "${data.title}"`); } else if (event.startsWith('category.')) { console.log(`${event}: category ${data.id} "${data.name}"`); } else if (event.startsWith('site.')) { console.log(`${event}: help center ${data.id} is ${data.visibility}`); } else { console.log(`ignored ${event}`); } } const server = http.createServer((req, res) => { if (req.method !== 'POST' || req.url !== '/webhooks/helpcenter') { res.writeHead(404).end(); return; } const chunks = []; req.on('data', (chunk) => chunks.push(chunk)); req.on('end', () => { const rawBody = Buffer.concat(chunks); const signature = req.headers['x-hcio-signature']; if (!SECRET || !isValidSignature(rawBody, signature)) { res.writeHead(401).end('Invalid signature'); return; } let payload; try { payload = JSON.parse(rawBody.toString('utf8')); } catch { res.writeHead(400).end('Invalid JSON'); return; } // Answer first: HelpCenter.io waits 10 seconds at most. res.writeHead(204).end(); // A retry repeats the body and the signature exactly. if (seen.has(signature)) return; seen.add(signature); setImmediate(() => handleEvent(payload)); }); }); server.listen(PORT, () => { console.log(`Listening on http://localhost:${PORT}/webhooks/helpcenter`); }); ``` ``` # server.py: receive HelpCenter.io webhooks (Python 3.8+, standard library only) import hashlib import hmac import json import os import queue import threading from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer SECRET = os.environ["HELPCENTER_WEBHOOK_SECRET"].encode() PORT = int(os.environ.get("PORT", "3000")) jobs = queue.Queue() seen = set() # Deliveries already handled. Use your database in production. seen_lock = threading.Lock() def is_valid_signature(raw_body, header): expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected.encode(), (header or "").encode()) def handle_event(payload): event, data = payload["event"], payload["data"] if event.startswith("article."): print(f'{event}: article {data["id"]} "{data["title"]}"', flush=True) elif event.startswith("category."): print(f'{event}: category {data["id"]} "{data["name"]}"', flush=True) elif event.startswith("site."): print(f'{event}: help center {data["id"]} is {data["visibility"]}', flush=True) else: print(f"ignored {event}", flush=True) def worker(): while True: handle_event(jobs.get()) class WebhookHandler(BaseHTTPRequestHandler): def do_POST(self): if self.path != "/webhooks/helpcenter": self.send_response(404) self.end_headers() return raw_body = self.rfile.read(int(self.headers.get("Content-Length", 0))) signature = self.headers.get("X-HCio-Signature", "") if not is_valid_signature(raw_body, signature): self.send_response(401) self.end_headers() return try: payload = json.loads(raw_body) except ValueError: self.send_response(400) self.end_headers() return # Answer first: HelpCenter.io waits 10 seconds at most. self.send_response(204) self.end_headers() # A retry repeats the body and the signature exactly. with seen_lock: if signature in seen: return seen.add(signature) jobs.put(payload) def log_message(self, format, *args): pass # Print only the events below. threading.Thread(target=worker, daemon=True).start() print(f"Listening on http://localhost:{PORT}/webhooks/helpcenter", flush=True) ThreadingHTTPServer(("", PORT), WebhookHandler).serve_forever() ``` ```