A thorough webhook testing workflow has four stages:<\/p>\n\n\n\n Before writing handler code, see what the actual payload looks like. These tools let you receive and inspect webhook payloads without deploying anything.<\/p>\n\n\n\n webhook.site<\/a> generates a unique URL that captures incoming HTTP requests. Point your Tolinku webhook at this URL, send a test event, and inspect the full request: headers, body, method, and timing.<\/p>\n\n\n\n How to use it:<\/p>\n\n\n\n You'll see:<\/p>\n\n\n\n This is the fastest way to understand the payload structure before writing any code. The free tier captures up to 500 requests per URL.<\/p>\n\n\n\n Pipedream's RequestBin<\/a> works similarly to webhook.site but adds workflow capabilities. You can:<\/p>\n\n\n\n It's useful when you want to prototype the transformation logic before building a dedicated receiver.<\/p>\n\n\n\n Beeceptor<\/a> creates mock API endpoints that can return custom responses. Beyond inspection, you can:<\/p>\n\n\n\n This is particularly useful for testing how Tolinku's retry logic behaves when your endpoint returns errors. Tolinku retries on non-2xx responses with delays of 1 minute, 5 minutes, and 30 minutes.<\/p>\n\n\n\n Once you know what the payload looks like, build your receiver locally and test it with real webhook events. The challenge: your local machine isn't publicly accessible. These tools solve that.<\/p>\n\n\n\n ngrok<\/a> creates a public tunnel to your local server. It's the most widely used tool for local webhook development.<\/p>\n\n\n\n ngrok outputs a public URL (e.g., ngrok's inspection dashboard (http:\/\/127.0.0.1:4040<\/a>) shows every request in real time: headers, body, response status, and timing. You can replay requests by clicking "Replay" in the dashboard, which is invaluable for debugging without retriggering the actual event.<\/p>\n\n\n\n Cloudflare Tunnel<\/a> (formerly Argo Tunnel) provides a similar capability but through Cloudflare's network. It's free and doesn't require an account for quick testing:<\/p>\n\n\n\n localtunnel<\/a> is a simpler, open-source alternative:<\/p>\n\n\n\n It generates a URL like Signature verification is the most common source of bugs in webhook integrations. Test it explicitly.<\/p>\n\n\n\n Create a standalone test that verifies your signature logic against a known payload and secret:<\/p>\n\n\n\n See the webhook security guide<\/a> for a full treatment of signature verification.<\/p>\n\n\n\n Real webhook traffic isn't a single event. It's a sequence: a click, then a deferred link claim, then an install, then maybe a referral completion. Your handler should process these in order and handle out-of-order delivery gracefully.<\/p>\n\n\n\n Create a script that sends a realistic sequence of events to your receiver:<\/p>\n\n\n\n Run this against your local receiver to validate the full event sequence.<\/p>\n\n\n\n Use the simulator to test scenarios that are hard to trigger manually:<\/p>\n\n\n\n The Tolinku dashboard includes a Test<\/strong> button on each webhook endpoint. This sends a test payload with:<\/p>\n\n\n\n The test event uses the same signing mechanism as production events, so it validates that your endpoint is reachable and your signature verification works. The dashboard shows the response status code and whether the delivery succeeded.<\/p>\n\n\n\n For full payload testing, trigger real events by clicking your actual deep links. Each click generates a After deploying your webhook receiver, check the delivery logs in the Tolinku dashboard. Each webhook endpoint shows:<\/p>\n\n\n\n If you see failed deliveries, check:<\/p>\n\n\n\n Add webhook handler tests to your CI pipeline. The unit tests for signature verification and payload processing should run on every commit. The integration test (simulator against a running receiver) can run as part of your staging deployment.<\/p>\n\n\n\n![\"Tolinku](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/platform-webhooks.png\")
\nThe webhooks page with create form, webhook list, and delivery log.<\/em><\/p>\n\n\n\nThe Testing Workflow<\/h2>\n\n\n\n
\n
Stage 1: Inspect the Payload<\/h2>\n\n\n\n
webhook.site<\/h3>\n\n\n\n
\n
https:\/\/webhook.site\/abc-123-def<\/code>)<\/li>\n\n
X-Webhook-Signature<\/code>, X-Webhook-Event<\/code>, Content-Type<\/code>, User-Agent: Tolinku\/1.0<\/code><\/li>\nevent<\/code>, timestamp<\/code>, and data<\/code> fields<\/li>\n<\/ul>\n\n\n\nRequestBin (Pipedream)<\/h3>\n\n\n\n
\n
Beeceptor<\/h3>\n\n\n\n
\n
Stage 2: Receive Locally<\/h2>\n\n\n\n
ngrok<\/h3>\n\n\n\n
# Start your local receiver on port 3000\nnpm run dev\n\n# In another terminal, create a tunnel\nngrok http 3000\n<\/code><\/pre>\n\n\n\nhttps:\/\/abc123.ngrok-free.app<\/code>). Use this URL as your Tolinku webhook endpoint.<\/p>\n\n\n\nCloudflare Tunnel<\/h3>\n\n\n\n
# Quick tunnel (no account needed)\ncloudflared tunnel --url http:\/\/localhost:3000\n<\/code><\/pre>\n\n\n\nlocaltunnel<\/h3>\n\n\n\n
npx localtunnel --port 3000\n<\/code><\/pre>\n\n\n\nhttps:\/\/quiet-fox-42.loca.lt<\/code>. It's less reliable than ngrok for long-running sessions but works well for quick tests.<\/p>\n\n\n\nStage 3: Verify Signatures<\/h2>\n\n\n\n
Write a Signature Test<\/h3>\n\n\n\n
import crypto from 'crypto';\nimport { describe, it, expect } from 'vitest';\n\ndescribe('webhook signature verification', () => {\n const secret = 'whsec_testsecret123456789012345678901234';\n\n it('should verify a valid signature', () => {\n const payload = JSON.stringify({\n event: 'link.clicked',\n timestamp: '2026-05-21T10:00:00.000Z',\n data: {\n prefix: 'go',\n token: 'test-link',\n hostname: 'links.example.com',\n ip: '203.0.113.1',\n platform: 'ios',\n device_type: 'mobile',\n campaign: 'test-campaign',\n },\n });\n\n const signature = crypto\n .createHmac('sha256', secret)\n .update(payload)\n .digest('hex');\n\n \/\/ Your verification function\n const isValid = verifySignature(payload, signature, secret);\n expect(isValid).toBe(true);\n });\n\n it('should reject a tampered payload', () => {\n const payload = '{"event":"link.clicked","tampered":true}';\n const wrongSignature = 'deadbeef1234567890';\n\n const isValid = verifySignature(payload, wrongSignature, secret);\n expect(isValid).toBe(false);\n });\n\n it('should reject an empty signature', () => {\n const payload = '{"event":"link.clicked"}';\n const isValid = verifySignature(payload, '', secret);\n expect(isValid).toBe(false);\n });\n});\n\nfunction verifySignature(\n body: string,\n signature: string,\n secret: string\n): boolean {\n if (!signature) return false;\n const expected = crypto\n .createHmac('sha256', secret)\n .update(body)\n .digest('hex');\n return crypto.timingSafeEqual(\n Buffer.from(signature),\n Buffer.from(expected)\n );\n}\n<\/code><\/pre>\n\n\n\nCommon Signature Pitfalls<\/h3>\n\n\n\n
\n
express.json()<\/code> middleware.<\/strong> This parses the body before your handler runs. Use express.raw({ type: 'application\/json' })<\/code> on your webhook route so you receive the raw Buffer.<\/li>\nStage 4: Simulate Event Sequences<\/h2>\n\n\n\n
Build a Webhook Simulator<\/h3>\n\n\n\n
import crypto from 'crypto';\n\nconst RECEIVER_URL = process.env.RECEIVER_URL || 'http:\/\/localhost:3000\/webhooks\/tolinku';\nconst SECRET = process.env.WEBHOOK_SECRET || 'whsec_testsecret123456789012345678901234';\n\nasync function sendEvent(event: any) {\n const body = JSON.stringify(event);\n const signature = crypto\n .createHmac('sha256', SECRET)\n .update(body)\n .digest('hex');\n\n const response = await fetch(RECEIVER_URL, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application\/json',\n 'X-Webhook-Signature': signature,\n 'X-Webhook-Event': event.event,\n 'User-Agent': 'Tolinku\/1.0',\n },\n body,\n });\n\n console.log(`${event.event}: ${response.status}`);\n}\n\nasync function simulateUserJourney() {\n const now = new Date();\n\n \/\/ Step 1: User clicks a campaign link\n await sendEvent({\n event: 'link.clicked',\n timestamp: now.toISOString(),\n data: {\n prefix: 'go',\n token: 'summer-promo',\n hostname: 'links.example.com',\n ip: '203.0.113.42',\n platform: 'ios',\n device_type: 'mobile',\n campaign: 'email-newsletter-may',\n },\n });\n\n \/\/ Step 2: User installs the app (30 seconds later)\n await sendEvent({\n event: 'deferred_link.claimed',\n timestamp: new Date(now.getTime() + 30000).toISOString(),\n data: {\n prefix: 'go',\n token: 'summer-promo',\n platform: 'ios',\n },\n });\n\n \/\/ Step 3: Install is tracked\n await sendEvent({\n event: 'install.tracked',\n timestamp: new Date(now.getTime() + 31000).toISOString(),\n data: {\n prefix: 'go',\n token: 'summer-promo',\n platform: 'ios',\n campaign: 'email-newsletter-may',\n },\n });\n\n console.log('Simulation complete: 3 events sent');\n}\n\nsimulateUserJourney();\n<\/code><\/pre>\n\n\n\nTest Edge Cases<\/h3>\n\n\n\n
\n
install.tracked<\/code> before link.clicked<\/code>. Does your handler cope?<\/li>\ndata.campaign<\/code> set to null<\/code>. Does your handler crash or handle it gracefully?<\/li>\nTolinku's Built-In Test Feature<\/h2>\n\n\n\n
{\n "event": "test",\n "timestamp": "2026-05-21T10:00:00.000Z",\n "data": {\n "message": "This is a test webhook from Tolinku.",\n "webhook_id": "wh_abc123",\n "appspace_id": "as_xyz789"\n }\n}\n<\/code><\/pre>\n\n\n\nlink.clicked<\/code> webhook within seconds.<\/p>\n\n\n\nMonitoring Deliveries<\/h2>\n\n\n\n
\n
\n
CI\/CD Integration<\/h2>\n\n\n\n
# Example GitHub Actions step\n- name: Test webhook handler\n run: |\n npm run test -- --filter webhook\n\n- name: Integration test\n run: |\n npm run dev &\n sleep 3\n npx tsx scripts\/webhook-simulator.ts\n<\/code><\/pre>\n\n\n\nTool Summary<\/h2>\n\n\n\n