Webhooks (Zapier, n8n, Power Automate)

A webhook is a URL you give us. When something specific happens in your shop — a quote wins, a job moves to QC, an NCR opens — GlyphFex sends a small message to that URL. Pair this with Zapier or Power Automate to do things like post to Slack, draft an invoice, or sync with your CRM.

What webhooks do

The Data Feed is great for “every 15 minutes, pull the latest snapshot.” Webhooks are for the opposite: the moment something specific happens, push it.

Configure a webhook URL and event type, and GlyphFex POSTs a small JSON payload to that URL every time the event fires. Six event types are supported:

The full payload schema is documented at the v1 webhooks reference.

Setting up a webhook

1. Open Settings Hub → Webhooks (Zapier, n8n).
2. Click Add Webhook.
3. Pick an event type from the dropdown.
4. Paste the destination URL. Must start with https:// — http:// is rejected at save time (and again at delivery time, as a defense-in-depth check).
5. GlyphFex generates a signing secret (32 random bytes, hex-encoded) and shows it once. Copy this into your receiver’s webhook configuration so it can verify the HMAC signature.
6. Click Send Test Event. GlyphFex posts a minimal test payload to the URL so you can confirm the round trip works before any real event fires.

You can configure multiple webhooks — one URL per (event type, destination) pair. For example, you might have quote_won firing to both Zapier (for Slack notifications) and an in-house URL (for ERP integration).

Security: HMAC signing, replay protection, HTTPS-only

Every webhook POST includes these headers:

• X-GlyphFex-Signature: sha256=<hex> — HMAC-SHA256 of the raw request body, keyed with the per-subscription signing secret. Reject any request where this header doesn’t verify.
• X-GlyphFex-Event-Id: <UUID> — Unique per delivery attempt. Store the last N IDs your receiver has seen and reject duplicates — that’s your replay protection.
• X-GlyphFex-Event: entry_created | stage_changed | … — Lets you route on type before parsing the body.
• X-GlyphFex-Timestamp: <ISO 8601 UTC> — When the event happened. GlyphFex drops deliveries older than 24 hours so a queue restart doesn’t flood your receiver with stale events.
• X-GlyphFex-Delivery-Attempt: <int> — 1 on the first attempt, 2 on the first retry, etc. Useful for idempotent-write logic on the receiver side.
• X-GlyphFex-Schema-Version: 1.0 — The payload schema version. v1.x is stable forever; v2 (if it ever ships) will run alongside v1 for at least 12 months.

HTTPS-only is enforced at two points: (1) when you save the subscription, the URL is rejected if it doesn’t start with https://; (2) when the delivery worker is about to POST, the URL is checked again so a sneaky in-place edit of the database can’t bypass it. Localhost http:// is also rejected — if you’re testing against a local receiver, use a tool like ngrok or cloudflared to get an HTTPS tunnel.

Retry, backoff, and circuit breaker

Webhooks are unreliable by nature — receiver downtime is a fact of life. GlyphFex retries each delivery up to 3 times with exponential backoff:

Any 2xx response (200–299) counts as a successful delivery. Any other response (or a connection failure / timeout) counts as a retryable failure. After 3 retries (4 total attempts) the delivery is marked Failed terminal and the worker moves on.

A circuit breaker tracks consecutive failures per subscription. If 50 consecutive deliveries fail (typically because the receiver has been permanently moved or decommissioned), the subscription auto-disables and stops queueing new deliveries until you re-enable it. You see a warning badge on the subscription in Settings Hub.

The payload

Every webhook body has the same envelope:

{
  "event_id": "01HXY5G6T2QZK0FZ3M9V7B5RZX",
  "event_type": "stage_changed",
  "event_timestamp": "2026-05-16T14:23:09Z",
  "schema_version": "1.0",
  "data": {
    "entry": { /* full v1 entry object */ }
  }
}

The data.entry object follows the same v1 schema as the Data Feed’s entries.json, so once you’ve coded against one, the other is free. Subscription ID is conveyed by which signing secret verifies the HMAC, not by a payload field. For event-specific context like a stage change’s “previous status,” read the entry’s stage_transitions array — the last entry is the new stage, the one before it is the previous.

The 1 MB cap and slim-envelope fallback

Webhook POSTs are capped at 1 MB. Most events fit easily; a few (entries with many attachments and a huge audit history) might exceed the limit. When they do, GlyphFex falls back to a slim envelope:

{
  "event_id": "...",
  "event_type": "stage_changed",
  "event_timestamp": "...",
  "schema_version": "1.0",
  "payload_truncated": true,
  "drop_reason": "Payload exceeded 1024 KB limit; full entry data omitted.",
  "data": {
    "entry": { "id": 12345, "ref_number": "WO-2026-0042" }
  }
}

The event still fires, the receiver still gets notified, but the full entry payload is replaced with just id and ref_number. Use those to query GlyphFex (via the Data Feed JSON or a future API) for the rest.

Common integration patterns

Slack / Teams: “Job moved into QC”

Slack and Teams don’t accept raw HMAC-signed webhooks directly — they expect their own payload shapes. Use Zapier or Power Automate as a translator:

1. In Zapier, create a Zap with a Webhooks by Zapier → Catch Hook trigger. Zapier gives you an HTTPS URL.
2. In GlyphFex, add a webhook subscription with event stage_changed and that URL. (Zapier verifies the HMAC for you if you configure the signing secret.)
3. In the Zap, add a Filter step: only continue if data.entry.status is QC. (The entry’s current stage is on data.entry.status; if you need the previous stage, it’s the second-to-last item in data.entry.stage_transitions.)
4. Add a Slack: Send Channel Message action. Use the templated body: {{data__entry__ref_number}} moved into QC.

The same shape works for Teams (Microsoft Teams Incoming Webhook), Discord, Mattermost, and most chat tools.

Accounting: “Auto-create an invoice when a quote is won”

Use n8n or Power Automate to route a quote_won event into your accounting system’s API. The data.entry object contains everything needed for an invoice draft — customer name, line items, quote total — so the receiver can construct the invoice without round-tripping back to GlyphFex.

Custom in-house: ERP sync

For an in-house receiver, you have direct control over HMAC verification. Verify the X-GlyphFex-Signature header against the raw body using your subscription’s signing secret. Track the last 1,000 X-GlyphFex-Event-Id values to dedupe replays. Return 200 quickly — if processing is slow, enqueue the event internally and process asynchronously.

Settings & Monitoring

In Settings Hub → Webhooks you can see per-subscription:

• Event type and URL
• Last delivery — timestamp, response code, latency
• Consecutive failure count — resets to 0 on the next success; triggers circuit breaker at 50
• Enabled / Disabled — toggle to pause without losing the subscription
• Rotate signing secret — generate a new secret and revoke the old one. Use this if you suspect the secret has been compromised or shared with someone who should no longer have access.
• Send test event — fires a minimal test payload so you can re-verify the round trip after a config change.
• Recent deliveries log — the last 50 deliveries with their status (Success / Failed / Pending) and response details.

Common questions

Can I get webhooks for every event in real-time AND a daily folder snapshot?

Yes — webhooks and the Data Feed are independent. Many shops do exactly this: webhooks for time-critical events (quote_won → Slack), Data Feed for the warehouse-scale reporting that Power BI does on a 15-minute cadence.

What happens if the receiver is down for a few hours?

The retry policy keeps trying for the first 36 seconds (4 attempts), then marks the delivery Failed and moves on. The event is not automatically retried days later — that’s by design, because GlyphFex doesn’t want to flood a previously-down receiver with hours of old events when it comes back. If you need to backfill, query the Data Feed’s entries.json for the window you missed.

Are webhooks available in the trial?

Yes. The 50-entry trial includes the full webhooks feature so you can validate the integration before purchasing. You can configure multiple subscriptions in trial mode.

Can webhooks include attachments?

Attachment metadata (filename, MIME type, path, size) is included in the payload. The binary file content is not — webhooks are designed for small, fast messages. If your receiver needs the actual file, use the path metadata to read it from your file server.

What HMAC verification library should I use?

Anything standard. In Node.js: crypto.createHmac('sha256', secret).update(rawBody).digest('hex'). In Python: hmac.new(secret_bytes, raw_body, hashlib.sha256).hexdigest(). In C#: new HMACSHA256(Encoding.UTF8.GetBytes(secret)).ComputeHash(rawBody). Always compare with a constant-time function (e.g., crypto.timingSafeEqual in Node) to defend against timing attacks.