> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/triggers-and-webhooks/outbound-webhook-subscriptions-and-event-payloads.md).

# Outbound Webhook Subscriptions and Event Payloads

Outbound webhook subscriptions store an HTTPS destination and selected event names. Creating a subscription does not enable run-event delivery. Use `GET /v2/runs/{run_id}` to observe workflow completion; a subscription is not a replacement for polling.

![Poll runs even after registering a subscription](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FDgDJbYYd8SBa2GdC8ReW%2Foutbound-webhook-subscriptions-and-event-payloads.png?alt=media)

The subscription route is shown as an operation, not a complete creation request. Registration does not enable run-event delivery. Where delivery is enabled, use Standard Webhooks verification and durable event-ID deduplication.

<details>

<summary>Copy the example</summary>

```http
# Subscription configuration
POST /v2/webhooks/subscriptions

# Run completion remains available through polling.
GET /v2/runs/{run_id}

# For enabled deliveries, verify the raw body with:
webhook-id: <event-id>
webhook-timestamp: <timestamp>
webhook-signature: <signature>
```

</details>

## Before you begin

An HTTPS receiver and permission to manage webhook subscriptions through the public API.

## Key concepts

| Term                   | Definition                                                                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Webhook subscription   | Registration of a destination and supported events for outbound notifications. Successful registration does not prove a particular event has been delivered.       |
| Event ID               | An identifier for a delivered event. Use it to recognize duplicates where the sender guarantees stable event identifiers.                                          |
| HMAC signature         | A message-authentication value calculated using a shared secret and payload. The receiver must use the same algorithm, encoding, and exact payload representation. |
| Raw body               | The original request bytes before parsing or reformatting. Signature verification can fail if the body is changed before verification.                             |
| Asynchronous operation | An operation acknowledged before its processing is complete. Retain its handle and follow its documented status or completion mechanism.                           |

## Register an event subscription

1. Create a subscription through `POST /v2/webhooks/subscriptions` with your HTTPS URL and accepted event types. Save the returned signing secret securely; list responses do not return it.
2. Keep polling the run status endpoint for completion. Successful subscription creation confirms configuration, not that a run will emit a notification.
3. If deliveries are enabled for your deployment, verify their signatures against the raw request body before processing. Use a Standard Webhooks verifier with the signing secret and the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers.
4. Deduplicate by event ID in durable storage. Return a successful response after durable acceptance, then process the accepted event asynchronously.

## Behavior and limitations

Accepted event names are `run.started`, `run.step.succeeded`, `run.step.failed`, `run.succeeded`, `run.failed`, and `run.cancelled`. These are subscription filters, not a guarantee of event production for every run. There is no public delivery-history or replay endpoint. Reject invalid or stale signatures, and do not assume event ordering or exactly-once delivery.

## Related resources

Trigger Activation and Execution Context

[Webhook subscription and signature reference](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/webhooks-and-signed-event-delivery.md)

[Run status and completion handling](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/run-workflows-end-to-end.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/triggers-and-webhooks/outbound-webhook-subscriptions-and-event-payloads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
