Skip to main content
Filter: one_shot (boolean)
Applies to: every webhook event
Set one_shot: true in a webhook’s filters to make it a one-time trigger: the subscription delivers once, then deletes itself. It is the webhook equivalent of a single-use alert, useful when you only care about the first time something happens and do not want to manage cleanup yourself.

​
How it works

When a delivery for a one_shot webhook succeeds, Struct deletes the subscription automatically. No further events are delivered, and the webhook no longer appears in GET /v1/webhooks.
  • Fires exactly once. If several events match in the same instant, only the first delivery goes out; the rest are dropped before the subscription is removed.
  • Deletes only on success. The subscription is removed after a delivery your endpoint acknowledges with a 2xx. If every retry fails, the webhook is not deleted: it follows the normal retry and auto-disable path instead, so a one-shot is never silently lost to a flaky endpoint.
  • Test deliveries are safe. A test delivery never consumes the one-shot or deletes the subscription, so you can verify your endpoint as many times as you like before the real event arrives.

​
Enabling it

Add one_shot to the filters object alongside any other filters for the event. The best fit is price_threshold: watch a market and fire the first time its price crosses your target, then remove the subscription. Here it fires once when a market’s YES outcome crosses up through 75%: 
import { StructClient } from "@structbuild/sdk";

const client = new StructClient({ apiKey: "sk_live_xxx" });

const { data: webhook } = await client.webhooks.create({
  url: "https://your-server.com/webhooks",
  event: "price_threshold",
  filters: {
    condition_ids: ["0x4fec624c0ff2bfae89956cebd6fbc9c58f995f824382dc587dc5a32a4b15940b"],
    min_probability: 0.75,
    one_shot: true,
  },
});
price_threshold requires position_ids or condition_ids when one_shot is set, so the subscription targets a bounded set of markets. The condition_ids above satisfies that.

​
Common patterns

  • First-of-a-kind events. Beyond price_threshold, catch the first whale trade on a market, the first new market in a category, or a single resolution, without leaving a long-lived subscription behind.
  • Self-cleaning automations. Spin up a webhook for a transient interest (a market you are watching today) and let it remove itself once it fires.

​
Notes

  • one_shot is available on every event’s filters and defaults to false.
  • The deletion is recorded with the event that triggered it, so you can trace why a subscription disappeared.
  • price_threshold additionally requires position_ids or condition_ids when one_shot is set, so the target stays bounded.
Last modified on June 15, 2026