> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/build/saas-connectors/saas-webhooks.md).

# Webhooks

Have fastn call your product back with a signed POST when something happens for one of your customers: account, setup link, provider and workflow events.

The connector you registered on the **API connector** tab of [Connect your product](https://docs.fastn.ai/build/saas-connectors.md) lets fastn call your product's API, using each customer's connection for the right connection scope. Webhooks cover the other direction: they let fastn call your product back when something happens for one of your customers.

Both live under **Connect your product**: the **API connector** tab is your product's connector, and the **Webhooks** tab is described on this page.

### What is the feature?

A webhook is a URL on your server. You give fastn the URL and pick the events you want, and fastn sends a POST request with a JSON body to that URL every time one of those events happens for a customer.

You can receive:

* **Account events**: a customer connects an app, removes it, or needs to sign in again.
* **Setup link events**: a setup link is used or expires unused.
* **Provider events**: an event from an app a customer connected, such as Jira or Linear, passed on unchanged.
* **Unified events**: the same app event in fastn's standard format.
* **Workflow events**: an event your own workflow sends. For example, after your workflow creates a ticket in Jira, Linear or ServiceNow for a customer, it can send the ticket details to your URL.

Each event carries the customer it belongs to, so your server knows which of your customers it is about.

### How does it work?

1. Something happens: an account is connected, an app sends an event, or your workflow sends one.
2. fastn checks which of your webhooks want that event and that customer, and reads each webhook's URL and payload schema.
3. fastn builds the request body. If the event is a workflow event and the webhook has a payload schema, the body is shaped to match it. Otherwise, fastn sends its standard format.
4. fastn sends a POST to your URL with the JSON body.

Every request is signed so your server can check it came from fastn. Each request has these headers:

* `X-Fastn-Event-Id`: a unique id for the event.
* `X-Fastn-Timestamp`: when the request was sent.
* `X-Fastn-Signature`: `sha256=` followed by an HMAC-SHA256 of `<timestamp>.<body>`, made with your webhook's signing secret.

To check a request, compute the HMAC over the raw request body, before you parse the JSON, and compare it in constant time. Reject a timestamp more than 5 minutes from your server's clock, so an old request can't be replayed.

```python
import hmac, hashlib, time

def verify(secret: str, headers, raw_body: bytes) -> bool:
    ts = headers["X-Fastn-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    want = "sha256=" + hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, headers["X-Fastn-Signature"])
```

If your server does not answer with a 2xx status within 10 seconds, fastn retries with growing gaps for up to 24 hours. Answer quickly and do slow work after you reply. The event id stays the same on every retry, so if you get the same id twice, ignore the second one.

### How can I add a webhook URL?

You need the Owner, Admin or Developer role.

1. In the fastn dashboard, open **Connect your product** and go to the **Webhooks** tab.
2. Click **Add webhook**.
3. Enter your **Endpoint URL**. It must be a public https address. fastn does not follow redirects.
4. Under **Events**, tick the events you want. All account and setup link events start ticked; untick any you don't need.
5. Under **Customers**, keep **All customers**, or pick one customer to send only that customer's events to this URL.
6. Optionally add a **Description**, such as "Production server".
7. Click **Add webhook**.

<figure><img src="https://1255842839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3iSr2Tx8FvvuoLPncziH%2Fuploads%2Fgit-blob-407a8d67ade88990f2e5f06ecc4f57b5213fb1a9%2Fsaas-webhooks-add-form.webp?alt=media" alt="The Add webhook form: Endpoint URL, Events grouped as Accounts, Setup links, Provider events and Workflow events, Customers set to All customers, and Description"><figcaption><p>The <strong>Add webhook</strong> form.</p></figcaption></figure>

8. Copy the signing secret that is shown. It is shown only once. Store it on your server and use it to check the `X-Fastn-Signature` header.

When you tick **Workflow events**, two more options appear:

* **Only these categories and connectors**: leave it on **Every connector** unless you want to limit which events are sent.
* **Only these workflow events**: the event names to send, comma separated (for example `ticket.created`). Leave it empty to send every name.

A workflow event is sent only when a workflow emits it: the workflow code calls `await fastn.events.emit("ticket.created", data, { connector: "jira" })`. Nothing is sent automatically when a workflow runs, and test runs never send.

From the webhook's row in the list you can:

* **Send test**: send a test event to the URL.
* **Edit**: change the URL, events or payload schema. The customer is set when the webhook is created and can't be changed.
* **Deliveries**: see recent deliveries and their status (Delivered, Retrying, Failed), and **Resend** any that is not still pending.
* **Pause**: stop sending for now. Events that happen while it is paused are not sent and don't appear in **Deliveries**. Deliveries already waiting to retry go out when you turn it back on; any still undelivered 24 hours after the event are marked failed, and you can replay them from **Deliveries**.
* **Rotate secret**: get a new signing secret. The old secret stops working at once, so update your server straight away. Deliveries still waiting to retry are signed with the new secret.

### How can I add schemas for different connectors?

A payload schema sets the exact JSON your server receives for workflow events. You list the fields you want, and for each one say where its value comes from in the event.

**Why you would need it:** different apps describe the same thing in different ways. A Jira issue has a key like `FIS-12`, a ServiceNow record has a number like `INC0010020`, and Linear uses an identifier like `ACM-12`. If your system expects a different body for Jira tickets than for ServiceNow records, give each connector its own schema. Your server then gets the shape it expects without translating each one.

To add one:

1. Open the webhook with **Edit** (or use the **Add webhook** form) and turn on **Payload schema**.
2. Click **+ Connector schema** and pick the connector, for example Jira.
3. Use the **Editing** dropdown to choose which schema you are working on.
4. Add each field with **Add field**: its name, its type, whether it is required, and **Value from**. With **Event path**, write where the value is in the event, for example `payload.ticket_url`. Paths starting with `payload.` read the data your workflow sent; `event`, `connector` and `tenantRef` read the event's own fields.
5. Check the result in the preview box under the table, then click **Add webhook** (when adding a webhook) or **Save** (when editing one).

You can also edit the schema as JSON in the **JSON Schema** tab, or start from **Use example**. If a field is marked **Required** and the event cannot fill it, that event is not sent, and the delivery log shows which field was missing. It is retried on the normal schedule for up to 24 hours, so if you fix the schema in that time, the waiting events go out. To send one straight away after a fix, use **Resend** in **Deliveries**.

An event uses the schema for the connector (or app) it names. If that has no schema, it uses the **Default** schema. If there is no Default schema either, it gets fastn's standard format.

### What if I want a single schema for all?

Add only a **Default** schema (click **+ Default**) and leave out the connector schemas. Every workflow event sent to that webhook will use it.

Example Default schema in the **JSON Schema** tab:

```json
{
  "type": "object",
  "required": ["event", "finding_id", "ticket_url"],
  "properties": {
    "event":      { "type": "string", "x-source": "event" },
    "finding_id": { "type": "string", "x-source": "payload.finding_id" },
    "ticket_url": { "type": "string", "x-source": "payload.ticket_url" }
  }
}
```

If you turn **Payload schema** off, fastn sends its standard format for each event type.

### Can my AI tool set this up for me?

Yes. If you have connected your AI tool to fastn's MCP server, you can ask it to do any of the steps above in plain language. For example:

* "Add a webhook for `https://example.com/fastn-events` that sends workflow events for all customers."
* "Add a payload schema to that webhook with these fields: event, finding\_id, ticket\_url."
* "Give Jira its own schema where ticket\_key comes from payload.issue\_key."
* "Send a test event and show me the last 5 deliveries."
* "Pause the webhook" or "Rotate the signing secret."

Your AI tool makes the same changes you would make in the dashboard, and they show up there right away. The signing secret is shown only once, so ask your AI tool for it right after it creates the webhook.


---

# 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.fastn.ai/build/saas-connectors/saas-webhooks.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.
