Metrickle

Outgoing webhooks

Last updated

A webhook sends a signed JSON request to your own endpoint when something happens in an app: a problem report, a gap in a protected task, a release that dropped something, a case opened or closed, a study booked. Use it to start your own workflows, or to feed a tool Metrickle doesn’t post to directly. Slack and Microsoft Teams are set up the same way and get a formatted message instead. See integrations for those.

Add a webhook

  1. Open the app’s Integrations page and choose Add Slack, Teams or webhook under Notify. You need to be an owner or admin, or have the integrations.manage permission.
  2. Choose Webhook, give it a name, paste your endpoint’s URL and pick the events to send.
  3. Copy the signing secret (whsec_…). It’s shown once.
  4. Send a test delivery to check your endpoint answers.

The URL must start with https:// and use a public host name, not localhost or an IP address. An app can have up to 20 destinations.

The request

Each delivery is a POST with a JSON body:

POST /your/endpoint
content-type: application/json
user-agent: Metrickle-Webhooks/1
metrickle-event: feedback.created
metrickle-delivery: evt_…
metrickle-signature: t=1790841234000,v1=5f2c…

{
  "id": "evt_…",
  "type": "feedback.created",
  "createdAt": 1790841234000,
  "app": { "id": "app_…", "name": "Quillmere" },
  "url": "https://app.metrickle.com/apps/app_…/feedback",
  "data": {
    "feedbackId": "…",
    "category": "accessibility",
    "accessibilityBarrier": true,
    "message": "The Pay now button can't be reached with Tab",
    "path": "/checkout",
    "a11y": ["keyboard"]
  }
}
FieldMeaning
idA unique id for this delivery, the same as the metrickle-delivery header
typeThe event type, the same as the metrickle-event header
createdAtWhen it was sent, in Unix milliseconds
appThe app it’s about
urlWhere to look in the dashboard
dataThe event’s details (below)

Check the signature

metrickle-signature is t=<unix ms>,v1=<hex>. The hex is an HMAC-SHA256, keyed with your signing secret, of the timestamp, a full stop and the raw request body. Check it on every request, and reject requests more than five minutes old:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string): boolean {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() - Number(t)) > 5 * 60_000) return false; // reject replays
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return typeof v1 === "string" && v1.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Use the body exactly as it arrived. Parsing and re-encoding the JSON changes it and the check fails.

Responses and retries

Any 2xx response within 5 seconds counts as delivered. A network error, a timeout, a 408, a 429 or a 5xx is tried twice more, after 1 second and then 4 seconds. Other responses aren’t retried. Each destination’s delivery log, on the Integrations page, shows the last 50 deliveries and what your endpoint answered.

Event types

TypeSent whendata fields
feedback.createdSomeone sends a problem report or other feedback, with accessibility barriers called outfeedbackId, category, accessibilityBarrier, message, rating, path, url, platform, appVersion, device, a11y, hasScreenshot, source
alert.task_success_dropA task’s success rate over the last 24 hours fell well below the 7 days before (baseline)taskId, taskName, appId, current, baseline, worstSegment, abandonedAt
alert.new_hotspotAn element or form started causing friction in the last 24 hourssignal, path, target, label, sessions, events
alert.contract_brokenA protected task’s verdict became Gap found: people using an accessibility setting, browser or device fall clearly behind the people they’re compared with since the latest release. baseline is that comparison grouptaskId, taskName, appId, verdict, segment, baseline, comparedWith, release, window
alert.release_droppedA release’s verdict became Drop found: a goal or protected task fell past its limit and clear of noise, or a group fell behind since the release. Sent once per releasereleaseId, version, verdict, lostPerMonth, impact, comparison, worst, counts, release, window
release.verdictA release got its first verdict, and it’s No drop or Early signal. Sent once per releasereleaseId, version, verdict, lostPerMonth, impact, comparison, worst, counts, release, window
case.openedA case opened on a protected task with a gap: the step, element and group of people that lose most, and what it costs. baseline is how the people they’re compared with didcaseId, taskId, taskName, status, finding, baseline, recordings, openedBy
case.closedA case closed: Fixed and verified (the task improved for the group that fell behind), or DismissedThe case.opened fields, plus resolution (verified or dismissed), after, closedAt, closeNote
issue.measured7 days after a linked issue is closed: the measure before and after the fixissueKey, issueUrl, title, improved, before, after
study.bookedSomeone booked, moved or cancelled a moderated research sessionchange (booked, moved or canceled, for a cancelled session), studyId, participantId, startsAt, endsAt, hasAccessNeeds
study.completedA participant finished an unmoderated test, or a moderator wrapped up a sessionstudyId, participantId, kind, tasksDone

In the API, protected tasks are called contracts, which is why the type is alert.contract_broken. The baseline fields are the comparison group: people using no accessibility settings, or everyone else on other browsers, systems or devices.

alert.task_success_drop and alert.new_hotspot also carry latestRelease (version, at, url) when there was a release in the 2 days before, since it’s often the cause.

For alert.release_dropped and release.verdict, verdict is dropped, watch (Early signal) or clear (No drop). worst is the check that did worst, as { "name", "kind", "status", "delta", "group" }: kind is task (a protected task) or goal, delta is the after rate minus the before rate (negative is a drop), and group is the key of the group it hit, such as browser:Safari or keyboard, or null. counts says how many checks there were and how many dropped, showed an early signal or were too early to tell. lostPerMonth is the largest single drop, valued as what it costs a month (Costing … a month in the dashboard), or null when no money is tracked. impact and comparison have the shapes described in release verdicts in CI, release is the release as recorded (with its source and environment), and window is the after window, { "from", "to" } in Unix milliseconds. See release verdicts.

alert.release_dropped is urgent: it’s emailed and pushed to the app’s members by default, with a title like “Release 4.12 dropped “Sign up””. release.verdict goes to the dashboard inbox by default, and to Slack, Teams, a webhook or email only if you choose it, with a title like “Release 4.12.1: No drop on 3 checks”.

For feedback.created, source is { "label", "url" } when the report came from a connected support inbox, such as Zendesk or Intercom, and null for reports sent in the app.

A test delivery has the type test and data of { "message": "This is a test delivery." }.

How often alerts are sent

Alerts are checked hourly. Each task alert is sent at most once a day, and each friction hotspot at most once a week.