Limit how much a webhook can send

A webhook sends every record that matches its saved search. If the search is broad, or you point it at the whole history of a search instead of only at new records, that can be a lot of credits in a short time.

You can bound it with a daily event limit (max_events_per_day): the most events the webhook can send in a day, resetting at midnight UTC.

It is empty by default, which means no limit. You can set it when you create a webhook, change it later, and send it through the API on POST /v0/webhooks and PATCH /v0/webhooks/{id}.

Events over the limit are not charged

The limit is applied when we create the events, before any credit is spent. An event stopped by the limit is never sent and never billed, so the limit caps what the webhook costs you and not just what it delivers.

This is also why pausing a webhook is not a substitute. Credits are charged when we scan for matches, not when we deliver them, so a webhook you deactivate at your budget and reactivate later charges the whole waiting backlog on its next scan.

Records over the limit are dropped, not queued

Each day sends that day's records only. If your limit is 100 and the search matched 150 records today, the other 50 are not sent, and they are not saved for tomorrow either, not even if tomorrow matches 30 and has room to spare.

This is on purpose. We only know that a day had spare room once the day is over, so a record carried over could not go out before the end of the following day. It would reach you about two days after we found it and cost the same credit as a fresh one. In most webhook use cases a two day old hiring signal is worth much less than a new one, so we keep the feed current instead.

If you need every match, raise the limit or narrow the search.

Sizing the limit

When you set a daily limit, the app shows how many records the search has matched per day over the last week, and warns you if your limit is below that, with the number of records a day you would lose. You can still save it. Getting less than everything is a normal thing to want, and the warning is there so that it is a decision instead of a surprise.

You can read the same estimate from the API:

curl "https://api.theirstack.com/v0/webhooks/volume-estimate?search_id=123" \
  -H "Authorization: Bearer $THEIRSTACK_API_KEY"

{
    "search_id": 123,
    "records_last_7_days": 1050,
    "avg_records_per_day": 150,
    "credits_per_record": 1,
    "avg_credits_per_day": 150
}

The estimate counts records by when we discovered them, which is when a webhook fires, and not by the date the source says the job was posted.

A webhook with trigger once per company is estimated in companies rather than in jobs, and in new ones: a company fires once and never again, so what matters is how many companies the search newly reaches each day, not how many it matches in total. The first scan may find 500 companies and the next one 3.

A company webhook has no daily estimate at all, and the app says so instead of guessing. It fires when a company starts matching filters about the company itself, such as headcount or the technologies it uses, and nothing records when that became true.

Things worth knowing

• The day is UTC, whatever timezone you work in. The events chart is drawn in your own local day, so the two do not line up: when a webhook has a limit, the chart says so and offers to redraw itself in UTC.
• Lowering the limit below what today already sent stops the webhook for the rest of the day. Nothing is refunded, and nothing is owed: those events were delivered.
• Raising the limit takes effect on the next scan. It does not recover the records that earlier scans dropped.
• A limit of 0 is a valid limit, and stops the webhook from sending anything.
• Credits still come first. If your balance runs out before the limit does, delivery stops there.