Agent skill

epilot Webhooks Skill

Receive and verify epilot (epilot.cloud) webhooks, signed per Standard Webhooks. Use when setting up an epilot webhook endpoint, getting the whsec_ signing secret, debugging webhook-id / webhook-timestamp / webhook-signature verification (including the extra v1a Ed25519 entry), or handling events like automation_trigger_webhook, customer_request_created and FileCreated.

Install this skill

npx skills add hookdeck/webhook-skills --skill epilot-webhooks


epilot is a cloud CRM and commerce platform for energy utilities. Each epilot webhook config subscribes to one organization event (an automation trigger, portal activity, entity or file events, Event Catalog events) and sends it to your URL (the API examples use POST), signed per Standard Webhooks with webhook-id, webhook-timestamp and webhook-signature headers.

When to Use This Skill

  • How do I receive epilot webhooks?
  • How do I verify an epilot webhook signature?
  • Why does webhook-signature hold two entries (v1a,... and v1,...)?
  • Where do I find my epilot webhook whsec_ signing secret?
  • How do I handle automation_trigger_webhook, customer_request_created or FileCreated events?
  • Why do epilot webhook retries fail verification after a few minutes?

Verification (core)

HeaderValue
webhook-idUnique message ID (e.g. msg_2a4f8b...), the same on every retry
webhook-timestampUnix seconds when the request was signed
webhook-signatureSpace-separated: v1a,<Ed25519> v1,<HMAC-SHA256>

Signed content is {webhook-id}.{webhook-timestamp}.{raw body}. The v1 key is the base64-decoded part of the webhook's whsec_ secret. The v1a Ed25519 entry proves the request came from your epilot organization. The examples skip it and verify v1, which proves the request was made for your webhook. The standardwebhooks library (npm, PyPI) ignores v1a for you.

const { Webhook } = require('standardwebhooks');

// epilot sends webhook-*; fall back to svix-* when webhook-id is absent
const p = req.get('webhook-id') ? 'webhook' : 'svix';
const headers = {
  'webhook-id': req.get(`${p}-id`),
  'webhook-timestamp': req.get(`${p}-timestamp`),
  'webhook-signature': req.get(`${p}-signature`),
};
// rawBody: exact request body string (express.raw({ type: '*/*' })), NOT re-serialised JSON
new Webhook(process.env.EPILOT_WEBHOOK_SECRET).verify(rawBody, headers, { jsonParse: false }); // throws → respond 400
const event = JSON.parse(rawBody);

Python: from standardwebhooks.webhooks import Webhook, then Webhook(secret).verify(raw_body, headers, json_parse=False), catching any exception.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Retries and the 5-minute window

epilot retries and Hookdeck replays resend the original webhook-timestamp. The library always enforces a fixed 5-minute window, so it rejects late retries (the schedule runs to 5 hours) and replays of older events. To drop or widen the window, use the manual verifier in references/verification.md: HMAC-SHA256 over {id}.{timestamp}.{raw body} with the same key, every v1,<base64> entry compared in constant time after a length check, and the timestamp required to be a plain positive integer.

Hookdeck configuration alert

Hookdeck's configuration alert for this source reads exactly:

Use the webhook's whsec_ signing secret, not API key, Basic or OAuth authentication. File deliveries in binary_multipart mode sign per-file metadata and fail verification.

Use the whsec_ secret returned when the webhook was created. Endpoint authentication (X-API-Key, Basic, OAuth bearer) can be configured alongside the signature but does not replace it.

Event Types and Payload

The event vocabulary is per organization. Each webhook config subscribes to one eventName from GET /v1/webhooks/events. The reliable join key is metadata.webhook_id, because one webhook config is one eventName.

EventFired when
automation_trigger_webhookAn automation action sends a webhook request (the most common trigger)
customer_request_createdA customer request is created (an example event name from an organization's list)
FileCreated (event_FileCreated)A file is created (Event Catalog envelope with _event_name, event_attachments)

Default body: { metadata, entity, relations, activity, changed_attributes }. metadata carries webhook_id, organization_id, correlation_id and optional automation and user IDs. The docs' payload example shows metadata.event_type, but their field table doesn't list it, so the examples fall back to _event_name. Details in references/overview.md.

Delivery Semantics

  • Default transport is JSON with Transfer-Encoding: chunked. A JSONata expression can reshape the body.
  • Each webhook config sets its own httpMethod (optional, with no documented default; the API examples use POST). Hookdeck's epilot source accepts only the methods you allow (custom methods), so if your epilot webhook uses another method, allow it on the source too. The examples accept GET, POST, PUT, PATCH and DELETE, verify the signature first for every method, and treat a missing body as empty bytes.
  • retryPolicy (new webhooks: enabled, maxAttempts 3, maximum 5) retries 5xx, 429 and connection errors after 5 s, 5 min, 30 min, 2 h and 5 h. Webhooks created before this feature don't retry.
  • Events are logged for 4 weeks and can be replayed.
  • File events can arrive as multipart/form-data (binary_multipart) or with Base64 bytes in the JSON (json_base64). binary_multipart signs per-file metadata, not the raw body, so the examples can't verify it (see the alert above).

Environment Variables

EPILOT_WEBHOOK_SECRET=whsec_xxxxx   # the webhook's signing secret; handlers fail closed (500) without it

The secret is returned only in the create response. A lost secret means recreating the webhook.

Local Development

# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 epilot --path /webhooks/epilot

Use the printed URL as the webhook URL in epilot. Details in references/setup.md.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →