Gareth Wilson Gareth Wilson

Guide to epilot Webhooks: Features and Best Practices

Published


epilot is a cloud CRM and commerce platform built for energy utilities, including the customer portals their customers log in to. Its webhooks push what happens there to your other systems: an automation step hands an entity to your ERP or billing system, a customer request is created, a portal user logs in, or a file such as an invoice is created. Utilities use them to keep billing, field service and document archives in step with the CRM.

What are epilot webhooks?

In epilot, a webhook config subscribes to a single event. To receive three kinds of event you create three configs, each with its own URL, settings and signing secret. The event names come from your organisation's own configuration, which GET /v1/webhooks/events lists, rather than from a fixed public catalogue.

A config also decides how the request is sent. You choose the HTTP method (POST in epilot's examples), optional endpoint authentication, a filter, a JSONata expression that reshapes the body, a retry policy, and for file events a delivery mode. Requests are sent with Transfer-Encoding: chunked, which most servers handle and Microsoft Power Automate does not.

Every request is signed to the Standard Webhooks specification, and the webhook-signature header always carries two entries: a v1a Ed25519 signature that proves the request came from epilot, and a v1 HMAC that proves it was meant for your webhook.

epilot webhook features

FeatureDetails
Configurationepilot UI or the Webhooks API, one config per event
Event listPer organisation, from GET /v1/webhooks/events
HTTP methodConfigurable per webhook (httpMethod)
SignatureStandard Webhooks HMAC-SHA256 (v1) plus Ed25519 (v1a)
Signature headerwebhook-signature, with webhook-id and webhook-timestamp
SecretPer webhook, whsec_..., returned once when the webhook is created
Endpoint authOptional X-API-Key, Basic or OAuth bearer, alongside the signature
BodyJSON, optionally reshaped with JSONata
Event routingBody field metadata.event_type
Retries5xx, 429 and connection errors, 3 attempts by default (up to 5)
HistoryEvents logged for 4 weeks, replayable
Source IPsOnly through the Enterprise static IP Secure Proxy

Events and payloads

EventTriggered whenCommon use cases
automation_trigger_webhookAn automation action sends a webhook request (the Automation Trigger Webhook, the most common trigger)Push an entity to an ERP or billing system
customer_request_createdA customer request is created (an example name from an organisation's event list)Open a ticket, notify a team
FileCreated (listed as event_FileCreated)A file is created. Event Catalog events use the event_* namingForward invoices and documents, optionally with the bytes
Portal activitiesA portal user accesses an entity (fires on every portal user login)Audit logins, sync contacts

Because one config carries one event, you often know the event from the URL the config points at. Inside the body, metadata.event_type names it, but epilot's field table doesn't list that field and a JSONata transform can remove it, so don't depend on it if you reshape payloads. epilot's examples all elide fields, and there are no complete published bodies.

File events have three delivery modes. The default sends references only. json_base64 embeds the file bytes in JSON. binary_multipart sends the files as multipart parts, and its signature covers a derived string of per-file hashes and metadata rather than the request body.

Setting up epilot webhooks

Create a config in the epilot UI or with the Webhooks API:

  • Event (eventName): one value from your organisation's event list.
  • URL and HTTP method. Hookdeck's epilot source pre-selects POST without enforcing it, so if you choose another method, allow it on the source as well.
  • Authentication, optional: an API key, Basic credentials or an OAuth client.
  • Filter, an optional JSONata expression, and the retry policy.
  • Delivery mode for file events. Pick references only or json_base64 if you want the signature to verify.

The response that creates the webhook contains its whsec_... signing secret. It isn't shown again, so store the whole value as EPILOT_WEBHOOK_SECRET straight away. A lost secret means recreating the webhook.

Endpoint authentication is a separate layer:

MethodWhat epilot sends
API keyYour configured key in X-API-Key
BasicAuthorization: Basic <base64 username:password> (use HTTPS)
OAuthAuthorization: Bearer <token> from your authorisation server, refreshed automatically

Hookdeck's configuration alert for this source puts it plainly: use the webhook's whsec_ signing secret, not API key, Basic or OAuth authentication. To route epilot through Hookdeck, create a source with the epilot type, paste that secret, and set the source URL on the webhook config. Then forward it locally with the Hookdeck CLI:

npx hookdeck-cli listen 3000 epilot --path /webhooks/epilot

Securing epilot webhooks

Both signatures cover <webhook-id>.<webhook-timestamp>.<raw body>. For the v1 HMAC, decode the secret after whsec_ and compute HMAC-SHA256. The header looks like v1a,<asymmetric> v1,<symmetric>. epilot's symmetric sample takes the second entry with split(" ")[1], which assumes v1a always comes first. The function below doesn't depend on order: it checks every v1, entry and ignores v1a,:

const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

To also check v1a, fetch your organisation's Ed25519 public key from https://webhooks.sls.epilot.io/v1/webhooks/.well-known/public-key?orgId=<org> and verify the same signed content.

epilot's sample rejects requests older than five minutes. epilot's own retries are re-sent by epilot, but a request that Hookdeck retries or replays keeps its original webhook-timestamp, and Hookdeck has no timestamp tolerance of its own. The function above checks only the signature.

The route accepts any method, because the config's httpMethod is yours to choose:

const express = require('express');

// store.save(webhookId, request) persists the request and resolves once it is durable.
function createEpilotReceiver(store) {
  const app = express();
  app.all('/webhooks/epilot', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.EPILOT_WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
    try {
      await store.save(req.headers['webhook-id'], { method: req.method, body: req.body });
    } catch {
      return res.sendStatus(503); // epilot retries 5xx on new webhooks
    }
    return res.sendStatus(200);
  });
  return app;
}

A Hookdeck epilot source checks the v1 HMAC and skips the v1a entry. When the HMAC doesn't match, Hookdeck still returns 200 to epilot and marks the request as failed verification instead of forwarding it.

Make epilot webhooks production-ready. Hookdeck Event Gateway verifies every epilot request, gives webhooks created before epilot's retry policy a retry layer, and keeps a searchable history of automation and portal events.

epilot webhook limitations and pain points

Older webhooks never retry

The Problem: An outage on your side loses events from some webhooks but not others.

Why It Happens: The retry policy is on by default for new webhooks only. Webhooks created before epilot added it have no retries, and even new ones stop after three attempts by default, five at most, with the last two hours and five hours after the previous failure.

Workarounds:

  • Check each webhook's retry policy and set maxAttempts to 5 where it matters.
  • Use epilot's four-week event log to replay what you missed.

How Hookdeck Can Help: Hookdeck accepts each event on epilot's first attempt and retries your service on its own schedule, so every webhook gets the same protection whatever its age.

The secret appears once

The Problem: You can't verify requests because nobody saved the secret.

Why It Happens: epilot returns the whsec_ value only in the create response, and each webhook has its own.

Workarounds:

  • Create webhooks through the API from a script that writes the secret straight into your secrets store.
  • Recreate the webhook if a secret is lost.

How Hookdeck Can Help: Keeping the secrets on Hookdeck sources, one per webhook, gives you one place to see which webhooks are verifying.

Multipart file deliveries can't be verified by body

The Problem: File events fail verification while every other event passes.

Why It Happens: In binary_multipart mode the signature covers per-file hashes and metadata, not the raw body that standard verifiers hash.

Workarounds:

  • Use references-only or json_base64 delivery when you need body-based verification.
  • If you must use multipart, verify with epilot's file-specific procedure in your own code.

How Hookdeck Can Help: Hookdeck's configuration alert for the epilot source flags this, and its request log shows the failed verifications so the cause is easy to spot.

No public list of events

The Problem: You can't plan an integration from the docs alone.

Why It Happens: Subscribable events depend on each organisation's configuration and the Event Catalog. The docs show examples only.

Workarounds:

  • Call GET /v1/webhooks/events for the organisation you're integrating with.

How Hookdeck Can Help: Pointing several epilot configs at one Hookdeck source lets you see every event type in one log while you work out which you need.

Best practices

Deduplicate on webhook-id

The body has no event ID, and webhook-id stays the same across retries. Use it the way the idempotency guide sets out.

Expect portal logins to be noisy

The portal user activity event fires on every portal login. Filter or aggregate it before it reaches systems that can't take that volume.

Allow the right IPs only if you have the proxy

Fixed source addresses exist only through the Enterprise static IP Secure Proxy (3.67.211.164, 18.196.226.8, 3.125.76.222), enabled on request. Without it, the signature is your only check on the sender.

Use JSONata carefully

A transform can make payloads friendlier, but it changes what your receiver parses and can drop metadata.event_type. Keep the event name in the output, or rely on the config's URL to identify the event.

Conclusion

epilot lets each webhook config choose its own event, method, auth, filter, transform and retry policy, and signs every request twice. Review each config on its own, starting with the secret you only see once.

Hookdeck Event Gateway gives every epilot webhook the same verification and retry behaviour, however it was configured. Create a free Hookdeck account.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.