Webhook deliveries

When a monitor fires, Tako posts one request to every notification channel listed on that monitor. This page describes that request: its headers, its body, how to verify the signature, and how Tako retries a delivery that fails. Tako follows the Standard Webhooks specification, so a library that verifies Standard Webhooks signatures verifies these.

Headers

Header	Value
`webhook-id`	The delivery id. Every retry of one delivery sends the same id, so use it to deduplicate.
`webhook-timestamp`	When Tako sent this attempt, in Unix seconds.
`webhook-signature`	`v1,` followed by the base64 HMAC-SHA256 signature.
`content-type`	`application/json`
`user-agent`	`Tako-Webhooks/1`

The request body

A channel whose kind is webhook receives JSON in this shape:

{
  "id": "4b1c2f2e-2a1b-4c7e-9f0a-6d3c1e5b8a90",
  "type": "monitor.fired",
  "created_at": "2026-09-12T20:05:00+00:00",
  "summary": "AAPL is up 3.2%, past your 3% threshold.",
  "monitor": {
    "id": "0d6f1e77-4b9a-4f0e-8a4d-2c9e7b1f3a55",
    "name": "AAPL big move",
    "type": "stocks.pct_change",
    "parameters": {
      "trading_item_id": 2590360,
      "window": "1d",
      "threshold": 3,
      "direction": "up"
    }
  },
  "firing": {
    "id": "9a7c5d31-8e2b-4a66-b0d7-5f4e3c2a1b09",
    "occurrence_key": "2026-09-12",
    "occurred_at": "2026-09-12T20:00:00+00:00",
    "trigger": "push"
  },
  "payload": {
    "ticker": "AAPL",
    "exchange": "XNAS",
    "window": "1d",
    "baseline_date": "2026-09-11",
    "baseline_close": 226.41,
    "price": 233.7,
    "percent_change": 3.2188
  }
}

Field	Type	Description
`id`	string	The delivery id, matching the `webhook-id` header.
`type`	string	The event type. Today the only value is `monitor.fired`.
`created_at`	string	When Tako recorded the firing, in ISO 8601.
`summary`	string	One sentence describing the firing, built from the monitor’s parameters and the payload. Tako builds it at delivery time, so the wording can change without the payload changing.
`monitor`	object	The monitor that fired.
`firing`	object	The firing itself.
`payload`	object	The values that caused the firing. Its fields depend on the monitor type.

monitor carries id, name, type, and parameters, which is the stored parameter object rather than the input you sent to Create a monitor. A type that resolves a subject stores the resolved value, so a monitor you created with a ticker carries a trading_item_id. firing carries id, occurrence_key, occurred_at, and trigger:

occurrence_key identifies the occurrence. Tako records one firing per key per monitor, so a source that reposts the same occurrence doesn’t fire twice.
occurred_at is when the occurrence happened in the data. created_at is when Tako recorded it. The gap between them is however long the source took to report.
trigger says what woke the monitor. push, meaning new data arrived, is the only value Tako sends today.

Verify the signature before you trust the body. Anyone who learns your channel’s URL can post to it. The signature is the only thing that proves a request came from Tako.

Verify the signature

Tako signs the concatenation of the delivery id, the timestamp, and the raw request body, joined with periods:

{webhook-id}.{webhook-timestamp}.{raw body}

The key is the base64-decoded part of your channel’s secret after the whsec_ prefix. The signature is v1, followed by the base64 HMAC-SHA256 digest. Sign the bytes you received, not a re-serialized object. Tako sends compact JSON with no spaces after separators, and any reformatting breaks the signature.

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify(secret: str, headers: dict[str, str], raw_body: bytes) -> bool:
    timestamp = int(headers["webhook-timestamp"])
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{headers['webhook-id']}.{timestamp}.".encode() + raw_body
    expected = "v1," + base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(expected, headers["webhook-signature"])

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 5 * 60;

export function verify(secret, headers, rawBody) {
  const timestamp = Number(headers["webhook-timestamp"]);
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const signed = Buffer.concat([
    Buffer.from(`${headers["webhook-id"]}.${timestamp}.`),
    rawBody,
  ]);
  const expected =
    "v1," + crypto.createHmac("sha256", key).update(signed).digest("base64");

  const received = Buffer.from(headers["webhook-signature"]);
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), received)
  );
}

Compare the signatures in constant time, and reject a webhook-timestamp far from the current time so an attacker can’t replay an old delivery.

How Tako retries

Tako allows 10 seconds for a response, and doesn’t follow redirects.

Response	What Tako does
`2xx`	Marks the delivery delivered.
`408`, `429`, or any `5xx`	Retries.
No response, such as a timeout or a connection error	Retries.
Any other status, including a `3xx` redirect	Fails the delivery without retrying.

A delivery gets 6 attempts: the first one, then retries after 1 minute, 5 minutes, 15 minutes, 1 hour, and 2 hours 45 minutes. Tako stops retrying a delivery more than 4 hours 30 minutes old, even when attempts remain. Respond 2xx as soon as you’ve stored the delivery, and do the slow work afterwards. A receiver that works for longer than 10 seconds gets retried, and receives the firing again. After 2 consecutive failed deliveries, Tako pauses the channel and sets its status_reason to delivery_failures. Monitors that post to a paused channel keep evaluating and recording firings, and those firings reach no one. Fix the destination, then resume the channel, which clears the consecutive-failure count. To see how each delivery went, call List a monitor’s firings and read deliveries.

Payload fields by monitor type

payload is a flat object of strings, numbers, booleans, and nulls. The fields depend on the monitor’s type.

stocks.pct_change

Field	Type	Description
`ticker`	string	The listing’s ticker.
`exchange`	string	The exchange’s ISO 10383 MIC.
`window`	string	The window you set: `1d`, `1w`, or `1m`.
`baseline_date`	string	The session date of the reference close.
`baseline_close`	number	The reference close the move is measured from.
`price`	number	The price that met the threshold.
`percent_change`	number	The move from `baseline_close` to `price`, in percent. Negative for a down move.

stocks.crosses

Field	Type	Description
`ticker`	string	The listing’s ticker.
`exchange`	string	The exchange’s ISO 10383 MIC.
`currency`	string, null	The exchange’s currency. Null when the exchange has none recorded.
`level`	number	The level you set.
`crossed`	string	`above` or `below`, the direction of the crossing.
`previous_date`	string	The session date of the prior close.
`previous_close`	number	The prior close, on the other side of the level.
`price`	number	The price that crossed.

stocks.new_52w_extreme

Field	Type	Description
`ticker`	string	The listing’s ticker.
`exchange`	string	The exchange’s ISO 10383 MIC.
`currency`	string, null	The exchange’s currency. Null when the exchange has none recorded.
`broke`	string	`high` or `low`, the end of the range the price passed.
`extreme_close`	number	The 52-week extreme the price passed.
`extreme_date`	string	The session date of that extreme.
`price`	number	The price that passed it.

crypto.crosses

Field	Type	Description
`ticker`	string, null	The asset’s ticker, such as `BTC`. Null when the asset carries none.
`name`	string	The asset’s name.
`coinmarketcap_id`	string	The CoinMarketCap id, which you can pass back as a `coinmarketcap_id`.
`level`	number	The level in USD you set.
`direction`	string	`above` or `below`, the direction you set.
`price`	number	The price in USD that reached the level.
`observed_at`	string	When the snapshot was taken, in ISO 8601.
`grain`	string	The sampling cadence the snapshot came from, as an ISO 8601 duration: `PT5M`, `PT30M`, or `P1D`.

sports.game_start

Field	Type	Description
`game_id`	string	The game’s id, as List sports games returns it.
`league`	string, null	The league’s name.
`team`	string, null	The team you watch.
`opponent`	string, null	The other team.
`home_team`	string, null	The home team.
`away_team`	string, null	The away team.
`start_time`	string	The scheduled start, in ISO 8601.

sports.game_result

Field	Type	Description
`game_id`	string	The game’s id, as List sports games returns it.
`league`	string, null	The league’s name.
`team`	string, null	The team you watch.
`opponent`	string, null	The other team.
`home_team`	string, null	The home team.
`away_team`	string, null	The away team.
`team_score`	integer	The final score for the team you watch.
`opponent_score`	integer	The final score for the other team.
`outcome`	string	`wins` or `loses`, from the watched team’s side. On a game-scoped monitor, it reads from the winner.
`margin`	integer	The margin of the result, always positive.
`winner`	string, null	The winning team’s name. Null when the feed carries no name.
`winner_id`	string, null	The winning team’s id, which you can pass back as a `team_id`.

sports.score_event

Field	Type	Description
`game_id`	string	The game’s id, as List sports games returns it.
`league`	string, null	The league’s name.
`team`	string, null	The team that scored. On a team-scoped monitor, that’s the team you watch.
`opponent`	string, null	The other team.
`side`	string, null	`home` or `away`, the side that scored.
`team_score`	integer	The score for `team`, after this score.
`opponent_score`	integer	The score for the other team.
`phase`	string	`live` or `final`, the state of the game when the score landed.

sports.odds_crosses

Field	Type	Description
`game_id`	string	The game’s id, as List sports games returns it.
`league`	string, null	The league’s name.
`home_team`	string, null	The home team.
`away_team`	string, null	The away team.
`team`	string, null	The team you named.
`opponent`	string, null	The other team.
`market`	string	The market you set: `moneyline`, `spread`, or `total`.
`market_type`	string	The feed’s market, which can be more specific than `market`. A `moneyline` reads `moneyline` or `3way`.
`side`	string, null	`over` or `under` for a total. Null for a moneyline or a spread.
`book`	string	The sportsbook’s display name.
`book_slug`	string, null	The sportsbook’s id, such as `draftkings`. Null when the feed carries no id.
`level`	number	The level you set.
`line`	number, null	The handicap or total that was quoted. Null for a moneyline, which has no line.
`price_american`	number, null	The quoted price in American odds.
`price_decimal`	number, null	The same price in decimal odds.
`open_line`	number, null	The opening handicap or total. Null for a moneyline.
`open_price_american`	number, null	The opening price in American odds.
`is_live`	boolean	True when the quote came from the live feed rather than the prematch one.

The fields a type sends are its contract. Tako can add a field, which your receiver should ignore, and removing one is a breaking change. While monitors is experimental, these shapes can change without a deprecation window.

Slack workflow bodies

A channel whose kind is slack_workflow receives a flat body of strings instead, because a Slack Workflow Builder trigger rejects nested values:

{
  "summary": "AAPL is up 3.2%, past your 3% threshold.",
  "monitor_name": "AAPL big move",
  "monitor_type": "stocks.pct_change",
  "monitor_id": "0d6f1e77-4b9a-4f0e-8a4d-2c9e7b1f3a55",
  "occurred_at": "2026-09-12T20:00:00+00:00",
  "event_id": "9a7c5d31-8e2b-4a66-b0d7-5f4e3c2a1b09",
  "event_type": "monitor.fired"
}

This shape carries no payload, so a receiver that needs the values that caused the firing needs a webhook channel. Tako signs and retries both kinds the same way.

What Tako accepts as a URL

Create a notification channel rejects a url that:

Doesn’t use https.
Uses a port other than 443 or 8443.
Embeds credentials, as in https://user:pass@example.com/hook.
Has a host that doesn’t resolve.
Has a host that resolves to a loopback, link-local, multicast, private, reserved, or shared address.

Tako normalizes the URL it stores: it lowercases the host, drops the fragment, and gives a bare host a trailing slash. Read url in the response to see what Tako posts to.

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

Webhook deliveries

Headers

The request body

Verify the signature

How Tako retries

Payload fields by monitor type

Slack workflow bodies

What Tako accepts as a URL

​Headers

​The request body

​Verify the signature

​How Tako retries

​Payload fields by monitor type

​Slack workflow bodies

​What Tako accepts as a URL

Headers

The request body

Verify the signature

How Tako retries

Payload fields by monitor type

Slack workflow bodies

What Tako accepts as a URL