Verify webhook requests

Anyone can send a request to your webhook URL. Before you act on an event, confirm that Nexiom Connect sent it and that nobody changed it on the way. Every delivery is signed with your endpoint's signing secret; the SDKs check the signature, the timestamp, and the payload in one call.

Verify with the SDK#

Pass the raw request body, the request headers, and your signing secret to webhooks.constructEventAsync in the Node.js SDK (0.4.0 or later) or webhooks->constructEvent in the PHP SDK (0.4.0 or later). It returns the event when the request is genuine, and fails when it isn't. It makes no network request: Node.js verifies the signature with the runtime's Web Crypto API, which is why its method is asynchronous, and PHP with hash_hmac.

import express from 'express';
import { NexiomConnect, NexiomWebhookVerificationError } from '@nexiom/connect';

const nexiom = new NexiomConnect({ apiKey: process.env.NEXIOM_API_KEY });
const secret = process.env.NEXIOM_WEBHOOK_SECRET;

const app = express();

// Keep the body as raw bytes: parsed and re-serialized JSON no longer matches the signature.
app.post('/webhooks/nexiom', express.raw({ type: 'application/json' }), async (request, response) => {
  let event;

  try {
    event = await nexiom.webhooks.constructEventAsync(request.body, request.headers, secret);
  } catch (error) {
    if (error instanceof NexiomWebhookVerificationError) {
      return response.status(400).send(error.reason);
    }

    throw error;
  }

  switch (event.type) {
    case 'email.delivered':
      console.log(`Delivered to ${event.data.recipient}`);
      break;
    case 'whatsapp.message.failed':
      console.log(`WhatsApp message ${event.data.id} failed: ${event.data.failure_code}`);
      break;
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  response.sendStatus(204);
});

In Laravel, define the route in routes/api.php (on Laravel 11 and later, run php artisan install:api once to create it). Those routes skip CSRF protection and are served under /api, so this endpoint's URL is https://your-app.example/api/webhooks/nexiom. Add the API key and signing secret to config/services.php, from your .env:

// config/services.php

'nexiom' => [
    'key' => env('NEXIOM_API_KEY'),
    'webhook_secret' => env('NEXIOM_WEBHOOK_SECRET'),
],

Respond with a 2xx status quickly, then do the work. To make processing reliable, store the event before you respond; see Webhook ingester.

What it checks#

The SDKs return the event only when every check passes:

The verified event is the event envelope:

In TypeScript, the result is a union of every documented event: checking event.type narrows event.data to that event's fields. An event type added after your SDK version is still verified and returned, so keep a default branch.

Options#

Errors#

A failed check rejects with NexiomWebhookVerificationError in Node.js and throws NexiomWebhookVerificationException in PHP. Its reason says which check failed:

Respond 400 to a request that fails verification, and never process it.

Get the raw body#

The signature covers the exact bytes Nexiom Connect sent. Read the body before anything parses it:

Signing secrets#

Each webhook endpoint has its own signing secret, starting with whsec_. It is shown once, when you create the endpoint in the dashboard. Store it with your other server secrets, and give each environment its own endpoint and secret.

Your API key is not a signing secret, and a signing secret cannot call the API. Never put either in client-side code or logs.

Verify without an SDK#

In other languages, verify the request yourself:

1. Read the headers

   Read x-nexiom-timestamp, the Unix time in seconds of this delivery attempt, and x-nexiom-signature, a hexadecimal HMAC-SHA256.

2. Check the timestamp

   Reject the request when the timestamp is more than 5 minutes away from your server's clock, in either direction.

3. Compute the signature

   Compute HMAC-SHA256 over the timestamp, a period, and the raw body, using the full signing secret as the UTF-8 key. Keep the whsec_ prefix; don't decode it.

   Text

   HMAC-SHA256(secret, timestamp + "." + rawBody)

4. Compare in constant time

   Compare your hexadecimal result with x-nexiom-signature using a constant-time comparison, then parse the JSON.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody: Buffer, timestamp: string, signature: string, secret: string): boolean {
  if (!secret || !/^\d+$/.test(timestamp) || !/^[a-f0-9]{64}$/i.test(signature)) {
    return false;
  }

  const seconds = Number(timestamp);
  const now = Math.floor(Date.now() / 1000);

  if (!Number.isSafeInteger(seconds) || Math.abs(now - seconds) > 300) {
    return false;
  }

  const expected = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');

  return received.length === expected.length && timingSafeEqual(received, expected);
}

Troubleshooting#