Outbound Webhooks & Event Subscriptions

EntraLane Outbound Webhooks allow your external backend systems, CRMs (HubSpot, Salesforce), automation platforms (Make, n8n, Zapier), and analytics services to react instantly to queue events as they happen in your physical locations.

Whenever a ticket is created, called to a counter, served, or marked as completed, EntraLane dispatches an authenticated HTTP POST request to your HTTPS endpoint within milliseconds.

Plan Availability

Real-time Outbound Webhooks (up to 5 active endpoints per organization) are included in the Pro and Business monthly plans, all Event Passes (Flash 24h, Weekend 72h, Festival 7 Days), and the 14-day Free Trial.

---

1. Supported Lifecycle Events

You can subscribe to individual event topics or all events simultaneously:

Event Name	Trigger Moment	Common Use Cases
ticket.created	Visitor checks in at an entrance kiosk, scans a dynamic QR code, or is manually queued by an operator.	Log customer arrival in CRM; trigger welcome SMS or digital loyalty greeting.
ticket.called	Operator clicks Call Next or calls a specific ticket to a service desk.	Flash counter signage; push notification or pager integration.
ticket.serving	Operator clicks Start Serving when the visitor arrives at the counter.	Start billable consultation timer; update physical counter availability.
ticket.completed	Operator finishes consultation and completes the ticket.	Prompt customer satisfaction (CSAT) survey; update case record in ERP.
ticket.noshow	Visitor does not appear within the grace period and is flagged as no-show.	Release scheduled staff slot; record missed appointment in calendar.
ticket.test	Triggered manually via the Send Test Ping button in the Admin portal.	Verify endpoint connectivity, latency, and signature validation.

---

2. Webhook Event Envelope & Payload

Every webhook request delivers a JSON payload with a standardized metadata envelope:

{
  "id": "evt_0192e2b34a127f8ba321bc4589d12345",
  "type": "ticket.called",
  "created": 1730361600,
  "tenantId": "c8a1e2f3-1234-4567-89ab-cdef01234567",
  "data": {
    "ticketId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "ticketNumber": "A-042",
    "sequenceNumber": 42,
    "serviceName": "Express Consultation",
    "status": "Called"
  }
}

Top-Level Fields

• id (string): Unique event identifier with prefix evt_. Ideal for idempotency deduplication on your receiving server.
• type (string): The event type name (e.g., ticket.called).
• created (integer): Unix epoch timestamp in seconds when the event was generated.
• tenantId (UUID): The EntraLane organization ID originating the event.
• data (object): Event payload containing ticket numbers, service designations, and lifecycle statuses.

---

3. Cryptographic Signature Verification (HMAC-SHA256)

To protect your receiving server from tampering, spoofing, and replay attacks, EntraLane signs every outbound webhook payload with an HMAC-SHA256 signature using your webhook endpoint’s secret key (whsec_...).

Request Headers

EntraLane includes two custom HTTP headers with each webhook POST:

X-EntraLane-Event: ticket.called
X-EntraLane-Signature: t=1730361600,v1=5d41402abc4b2a76b9719d911017c592...
Content-Type: application/json

• X-EntraLane-Event: The subscribed event identifier.
• X-EntraLane-Signature: Contains the Unix timestamp (t=...) and the hex-encoded HMAC-SHA256 hash (v1=...).

Verification Steps

1. Extract the timestamp t and the signature v1 from the X-EntraLane-Signature header.
2. Verify that Math.abs(current_unix_time - t) < 300 (5 minutes) to protect against replay attacks.
3. Create the signature preimage string by concatenating the timestamp, a literal period ., and the exact raw request body string:

   signedPayload = `${t}.${rawRequestBody}`

4. Compute the HMAC-SHA256 of signedPayload using your secret key (whsec_...).
5. Compare your computed hex digest with v1 using a constant-time comparison function.

Verification Code Examples

Node.js / TypeScript

import crypto from 'node:crypto';
import type { Request, Response } from 'express';

export function verifyEntraLaneWebhook(
  req: Request,
  res: Response,
  secretKey: string
): boolean {
  const signatureHeader = req.headers['x-entralane-signature'] as string;
  if (!signatureHeader) return false;

  const elements = Object.fromEntries(
    signatureHeader.split(',').map((part) => part.split('='))
  );

  const timestamp = parseInt(elements['t'], 10);
  const expectedHash = elements['v1'];

  // 1. Prevent replay attacks (5 minute threshold)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) {
    return false;
  }

  // 2. Compute HMAC over "${timestamp}.${rawBody}"
  // NOTE: req.rawBody must be the unparsed UTF-8 Buffer/string
  const signedPayload = `${timestamp}.${req.rawBody}`;
  const computedHash = crypto
    .createHmac('sha256', secretKey)
    .update(signedPayload, 'utf8')
    .digest('hex');

  // 3. Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(computedHash, 'hex'),
    Buffer.from(expectedHash, 'hex')
  );
}

C# (.NET)

using System.Security.Cryptography;
using System.Text;

public static class EntraLaneWebhookValidator
{
    public static bool VerifySignature(
        string rawJsonBody,
        string signatureHeader,
        string secretKey)
    {
        if (string.IsNullOrWhiteSpace(signatureHeader)) return false;

        var parts = signatureHeader.Split(',')
            .Select(p => p.Split('='))
            .ToDictionary(p => p[0].Trim(), p => p[1].Trim());

        if (!parts.TryGetValue("t", out var tStr) || !parts.TryGetValue("v1", out var expectedHex))
            return false;

        if (!long.TryParse(tStr, out var timestamp))
            return false;

        // 1. Replay attack check (5-minute tolerance)
        var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        if (Math.Abs(now - timestamp) > 300)
            return false;

        // 2. Compute HMAC-SHA256
        var signedPayload = $"{timestamp}.{rawJsonBody}";
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));
        var computedBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(signedPayload));
        var expectedBytes = Convert.FromHexString(expectedHex);

        // 3. Constant-time comparison
        return CryptographicOperations.FixedTimeEquals(computedBytes, expectedBytes);
    }
}

Python

import hmac
import hashlib
import time

def verify_entralane_webhook(raw_body: bytes, signature_header: str, secret_key: str) -> bool:
    if not signature_header:
        return False

    parts = dict(item.split('=') for item in signature_header.split(','))
    timestamp = int(parts.get('t', 0))
    expected_hash = parts.get('v1', '')

    # 1. Replay check (5 minutes tolerance)
    if abs(int(time.time()) - timestamp) > 300:
        return False

    # 2. Compute HMAC-SHA256
    signed_payload = f"{timestamp}.".encode('utf-8') + raw_body
    computed_hash = hmac.new(
        secret_key.encode('utf-8'),
        signed_payload,
        hashlib.sha256
    ).hexdigest()

    # 3. Constant-time comparison
    return hmac.compare_digest(computed_hash, expected_hash)

---

4. Setting Up Webhooks in the Admin Portal

1. Open Webhooks Management Log into the EntraLane Management Portal and navigate to Organization → Webhooks (/app/webhooks).

2. Add a Webhook Endpoint Click Add Webhook in the top toolbar.

3. Provide Endpoint URL & Events

   • Enter your public HTTPS URL (e.g., https://api.yourdomain.com/webhooks/entralane).
   • Select the queue events you wish to receive (ticket.created, ticket.called, ticket.serving, ticket.completed, ticket.noshow).
   • (Optional) Specify a custom secret key or let EntraLane generate a cryptographically random secret (whsec_...).

4. Save & Copy Signing Secret Click Create Webhook. Copy the displayed Signing Secret immediately into your server’s environment configuration.

5. Send Test Ping Click Send Test Ping next to your newly created webhook. EntraLane sends a synthetic ticket.test event (sequenceNumber: 42, ticketNumber: "A042") and displays the HTTP response status code in real time.

---

5. Security & Infrastructure Protection

Anti-SSRF & DNS-Rebinding Protection

EntraLane validates target hosts at socket connection time. Requests to private subnets (RFC 1918 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback addresses (127.0.0.1), CGNAT (100.64.0.0/10), link-local IPs, and cloud metadata endpoints (169.254.169.254) are strictly blocked.

HTTPS Strictly Enforced

All webhook endpoints must use secure https:// URLs. Plaintext http:// endpoints are rejected upon creation.

Automated Retries & Backoff

If your endpoint returns an HTTP 5xx error or times out (>3 seconds), EntraLane automatically retries delivery up to 3 times with exponential backoff.

Circuit Breaker Safeguard

If an endpoint fails 10 consecutive delivery attempts, EntraLane automatically marks the webhook subscription as Inactive to prevent cascading failures. You can re-enable the subscription in your admin settings once your service recovers.

Best Practice: Fast Responses

Your webhook listener should respond with an HTTP 200 OK or 204 No Content as quickly as possible (ideally under 500ms). Offload heavy background tasks, database mutations, or external API calls to an internal queue (e.g., RabbitMQ, Redis BullMQ, or Celery).