Guide to epilot Webhooks: Features and Best Practices
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
| Feature | Details |
|---|---|
| Configuration | epilot UI or the Webhooks API, one config per event |
| Event list | Per organisation, from GET /v1/webhooks/events |
| HTTP method | Configurable per webhook (httpMethod) |
| Signature | Standard Webhooks HMAC-SHA256 (v1) plus Ed25519 (v1a) |
| Signature header | webhook-signature, with webhook-id and webhook-timestamp |
| Secret | Per webhook, whsec_..., returned once when the webhook is created |
| Endpoint auth | Optional X-API-Key, Basic or OAuth bearer, alongside the signature |
| Body | JSON, optionally reshaped with JSONata |
| Event routing | Body field metadata.event_type |
| Retries | 5xx, 429 and connection errors, 3 attempts by default (up to 5) |
| History | Events logged for 4 weeks, replayable |
| Source IPs | Only through the Enterprise static IP Secure Proxy |
Events and payloads
| Event | Triggered when | Common use cases |
|---|---|---|
automation_ | An 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_created | A 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_* naming | Forward invoices and documents, optionally with the bytes |
| Portal activities | A 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
POSTwithout 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_base64if 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:
| Method | What epilot sends |
|---|---|
| API key | Your configured key in X-API-Key |
| Basic | Authorization: Basic <base64 username:password> (use HTTPS) |
| OAuth | Authorization: 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
maxAttemptsto 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_base64delivery 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/eventsfor 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.