> For the complete documentation index, see [llms.txt](https://support.attackforge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.attackforge.com/app/automations-and-integrations/self-service-events-api.md).

# Self-Service Events API

## Overview

The Self-Service Events API tells you the moment something happens in AttackForge, such as a vulnerability being created or a project changing status. Your systems react straight away, instead of checking the API over and over for changes.

Each user can receive only the events an administrator has given them access to.

{% hint style="info" %}
**Tip:** For the full list of events and how to connect, see the [Events API documentation](https://docs.attackforge.com/events-api/pages/getting-started).
{% endhint %}

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FCSnyUHySQlaOMyZQGdXt%2Fself-service-events-api-at-a-glance.svg?alt=media&amp;token=fe0fe470-b797-4d0f-b34f-1693478a34dc" alt=""><figcaption></figcaption></figure>

## Why it matters

| Benefit                         | What it means                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| **Real time**                   | React as soon as something changes, not on the next scheduled check                 |
| **Less load**                   | No need to poll the Self-Service API repeatedly                                     |
| **Event-driven automation**     | Start Flows, tickets, alerts and AI agents from AttackForge events                  |
| **Least privilege**             | Every event is off by default. Each user, or group, gets only the events they need. |
| **Each user has their own key** | Connections are tied to a person, so they're easy to trace                          |

## Who uses it

| Role                                     | Typical use                                                  |
| ---------------------------------------- | ------------------------------------------------------------ |
| **Administrators**                       | Grant events to users and groups                             |
| **Automation builders**                  | Trigger Flows and AI agentic workflows from events           |
| **Developers and integration engineers** | Stream events into ticketing, chat, SIEM and data platforms  |
| **Security operations teams**            | Get alerted when Critical findings are raised or SLAs change |

## Choose how to use events

| Option               | Best for                                            | How                                                                                                                                                 |
| -------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flows**            | Automation inside AttackForge, with no code to host | Choose an event as a Flow's trigger. See [Flows](https://support.attackforge.com/app/automations-and-integrations/flows).                           |
| **WebSocket client** | Your own service that listens for events            | Connect to the Events channel with your API key. See the [Events API documentation](https://docs.attackforge.com/events-api/pages/getting-started). |

{% hint style="info" %}
Both need access to the events. Flows' event triggers use the Flow owner's access.
{% endhint %}

## See which events you can use

Go to **Integration Docs** in the main menu to see the events.

A padlock next to an event means you don't have access to it.

{% hint style="info" %}
**Important:** Every event is off by default for every user, including administrators.
{% endhint %}

You can get access in two ways:

* An administrator gives you access to the event directly.
* An administrator gives a group access to the event, and you're a member of that group.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FjeccDsPIRDRK4QbeXBPG%2Fimage.png?alt=media&amp;token=cdb13538-10e3-4f6a-b723-fb690e7249e5" alt=""><figcaption></figcaption></figure>

## Give users access to events

#### Give one user access

1. Go to **Users**, select the user, and click **Access**.
2. Expand **Events (Flows / Self-Service API)**, and click **Add Events**.
3. Select the events, and click **Add**.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F5SB2XZWj2DGwo6W8Udw0%2Fimage.png?alt=media&amp;token=cc4ccc71-3327-4039-84e6-441e9b33c874" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F62BZOEEVwQUCj6hWiE99%2Fimage.png?alt=media&amp;token=2b82a107-6f39-4dc3-92fc-15b0c4d29f8a" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2Fv55PEH80miG1vUKRdy30%2Fimage.png?alt=media&amp;token=15a4ee5c-a9e3-4f09-bc95-4467a90a5d54" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FpFacdMGJj6OdygaXzoyY%2Fimage.png?alt=media&amp;token=dcd6b969-d39d-4325-99ea-a37f4c075d3b" alt=""><figcaption></figcaption></figure>

#### Give a group access

1. Go to **Groups**, select the group, and click **Other Access**.
2. Expand **Events (Flows / Self-Service API)**, and click **Add Events**.
3. Select the events, and click **Add**.

{% hint style="info" %}
**Note:** Every member of the group can use the events you give the group.
{% endhint %}

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FV65P4WqU6GA6Zv2Dc0bY%2Fimage.png?alt=media&amp;token=02fb21e7-afa4-45d2-9d03-297516ff5c2e" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FbJlM0mJ7z8OTpzbPZ2HI%2Fimage.png?alt=media&amp;token=6ce1f02d-89ec-4260-a0d6-3efac2e304d0" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FHRkTFkbeex0wkwfRlbTd%2Fimage.png?alt=media&amp;token=c0e3ce88-644a-4a66-8ac6-ab48a964accd" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2Fw9062UNnWfC1uREXL6NO%2Fimage.png?alt=media&amp;token=35111a64-adfc-498b-b83a-c1729b5e053a" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F5kp2bUv7emdKVtJ3rQ3h%2Fimage.png?alt=media&amp;token=f9c9c009-1100-4289-aa92-d0c45c2e59d3" alt=""><figcaption></figcaption></figure>

## Create your API key

You need an API key to connect to the Events channel. It's the same key you use for the [Self-Service RESTful API](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api).

1. Log in to AttackForge, and go to **Profile**.
2. Click **Secrets**.
3. Under **API Key**, click **View Key**, **Copy Key** or **Rotate Key**.

{% hint style="info" %}
**Warning:** Users can only create, view and rotate their own key. Administrators can't do this for other users.
{% endhint %}

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FdaVkF4BefuVznybHmQzR%2Fimage.png?alt=media&amp;token=77627303-4cae-47f8-8245-9b031e63224e" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FTDW9wkTSgDPS63qC59Lv%2Fimage.png?alt=media&amp;token=352c5358-f484-495c-b909-aac32708a030" alt=""><figcaption></figcaption></figure>

## Receive events

### In a Flow

Create a Flow, and choose an event as its trigger. The Flow runs each time the event happens. See [Flows](https://support.attackforge.com/app/automations-and-integrations/flows).

### With a WebSocket client

Connect your own WebSocket client to the Events channel, sign in with your API key, and subscribe to the events you have access to. For the connection URL, message format and event payloads, see the [Events API documentation](https://docs.attackforge.com/events-api/pages/getting-started).

## Tips

* **Use Flows unless you need your own service.** Flows react to events with no code to host. Use a WebSocket client when your own system needs the events.
* **Grant events to groups.** Group access is easier to manage and review than user-by-user access.
* **Subscribe only to what you need.** Fewer events means less noise and less processing.
* **Use a dedicated user for integrations.** A listener with its own user and key is easy to trace and to switch off.
* **Reconnect automatically.** WebSocket connections can drop, so build your client to reconnect and resubscribe.
* **Fetch details with the API.** When an event arrives, use the [Self-Service RESTful API](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api) to get any extra data you need.
* **Start an AI agent from an event.** Combine an event-triggered Flow with an agent. See [AI agentic workflows](https://support.attackforge.com/app/automations-and-integrations/ai-agentic-workflows).
* **Keep your key secret,** and rotate it if it may have been exposed.

## FAQ

**Why do I see a padlock next to an event?** You don't have access to it. Ask an administrator to give you, or one of your groups, access.

**I'm an administrator. Why can't I receive events?** Every event is off by default, including for administrators. Give yourself access to the events you need.

**What's the difference between events and the Self-Service RESTful API?** The API answers when you ask. Events tell you when something changes, without you asking.

**Do I need to write code?** No, if you use Flows. Yes, if you connect your own WebSocket client.

**Is the Events API key the same as my Self-Service API key?** Yes.

**Can an administrator create or see my API key?** No. Only you can create, view and rotate your own key.

**Where's the list of events?** In **Integration Docs** in the app, and in the [Events API documentation](https://docs.attackforge.com/events-api/pages/getting-started).

## Related pages

* [Events API documentation](https://docs.attackforge.com/events-api/pages/getting-started): every event, and how to connect.
* [Flows](https://support.attackforge.com/app/automations-and-integrations/flows): trigger automation from events.
* [Self-Service RESTful API](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api): read and change data, and create your API key.
* [AI agentic workflows](https://support.attackforge.com/app/automations-and-integrations/ai-agentic-workflows): start AI agents from Flows.
* [AI MCP and Skills](https://support.attackforge.com/app/automations-and-integrations/ai-mcp-and-skills): let AI assistants work with your data.
* [Administration](https://support.attackforge.com/app/modules/administration): manage users and groups.


---

# 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://support.attackforge.com/app/automations-and-integrations/self-service-events-api.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.
