Skip to main content
This is a community example contributed by JR, founder of Telemetry. It has been tested locally only - it has not been deployed or exercised against the hosted services, and it is not an official or natively supported Hookr integration. Review the code and run it in a dedicated test workspace before relying on it.

​
Overview

This integration uses Hookr Forwarding to relay a small, fixed set of workflow event fields to telemetry.sh. Once the events land in a telemetry.sh table, you can query stage-completion metrics (counts and average durations) across many workflow runs. It complements - rather than replaces - Hookr’s push notifications and event history. Hookr still shows individual events and forwarding results; telemetry.sh adds an aggregate view.

​
How it works

A small adapter service sits between Hookr and telemetry.sh:
  1. Your application sends the workflow event as JSON by POST to a Hookr webhook.
  2. Hookr preserves the original method and forwards the raw payload to the adapter, signed with X-Hookr-Signature. The adapter accepts only POST and rejects anything else.
  3. The adapter verifies the signature, validates the event, and forwards only the allowed fields to the telemetry.sh Log API.
  4. You query the resulting table to analyze stage completions across runs.

​
Prerequisites

  • A Hookr webhook with Forwarding enabled, and its forward secret.
  • A telemetry.sh account and an API key.
  • A host that can run a Node.js service and expose it over public HTTPS.

​
Event contract

Your application must send events shaped exactly like this:
Only these five fields are forwarded onward. Everything else in the payload is dropped.
An allowlist does not make values safe. Never put customer identifiers, secrets, or other sensitive data in these fields.

​
Setup

1

Configure secrets

Provide the adapter with server-side secrets. Do not paste real credentials into the source files.
  • HOOKR_FORWARD_SECRET - your webhook’s forward secret
  • TELEMETRY_API_KEY - your telemetry.sh API key
  • HOOKR_ADAPTER_PORT - optional, defaults to 8080
2

Run the adapter

Get the adapter code from the source package, then start the server.mjs entry point:
The server listens only on 127.0.0.1. It accepts POST /hookr with a JSON body and rejects other methods, paths, and compressed bodies. It buffers at most 16 KiB per request and limits concurrency.
3

Expose it over HTTPS

Because the adapter binds to loopback only, put it behind a public HTTPS reverse proxy that forwards to /hookr, with suitable connection limits and monitoring. No public endpoint is included or deployed for you.
4

Point Hookr at the adapter

In your Hookr webhook’s Forwarding settings, set a destination URL that resolves to your proxy’s /hookr endpoint, and confirm the forward secret matches HOOKR_FORWARD_SECRET.

​
Verify

Using invented data in a dedicated test workspace:
  1. Forward one event through Hookr and inspect the forwarding response.
  2. Query the telemetry.sh table until the event is visible within a bounded wait.
  3. Test a rejected event and an ambiguous timeout separately.
The adapter returns 204 after an upstream 2xx. This means HTTP acceptance, not proven durable storage or immediate query visibility. Upstream failure or timeout returns an empty 502.

​
Analyzing results

The example includes an analysis query that collapses repeated event IDs, excludes conflicting IDs, and groups recorded completions by stage and outcome with an average duration. Note that it measures recorded completions only - a run without a completion event is absent, so the result is not a workflow success rate.

​
Security notes

  • Only five fields leave the adapter. Arbitrary payload properties, headers, and source credentials are never forwarded.
  • 204 is not durability. A timeout can occur after acceptance; the example does not implement a durable queue, replay protection, or exactly-once delivery.
  • No automatic retry. Investigate using the stable event_id before manually replaying.
  • The body signature authenticates bytes, not freshness. Repeated authentic payloads remain possible.

​
Full source

The complete adapter, server, ingestion client, analysis SQL, and local tests are available in the contributor’s source package:

Hookr → telemetry.sh source draft

Full source and local tests (Node and Python standard libraries only). All credentials in tests are invented fixtures.
For the telemetry.sh Log API, see the telemetry.sh documentation.