> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Forward security events as JSON to any HTTP endpoint you control

The Webhook integration posts each security event as a JSON payload to an endpoint you control. Use it to route alerts into a system OASM does not support natively — a chat bridge, a ticket queue, a SIEM, or a custom automation.

## Prerequisites

* An HTTP or HTTPS endpoint that accepts `POST` requests with a JSON body.
* Any authentication the endpoint needs, applied on the receiving side.

> [!WARNING]
>
> Use HTTPS. A plain HTTP endpoint sends alert contents in cleartext over the network.

## Connect Webhook

**1. Open the Applications tab**

In the console sidebar, open **Integrations** and select the **Applications** tab.

**2. Open Webhook**

Select the **Webhook** card.

**3. Enter a name and URL**

Enter an **Integration name**, then enter the **URL** that should receive the payloads.

**4. Choose events**

Use the **Event** and **Severity** switches to control what OASM sends. See [What notification integrations send](/integrations/overview#what-notification-integrations-send).

**5. Connect**

Select **Connect**. OASM posts a welcome payload to confirm the endpoint is reachable.

## Payload format

Each event is a `POST` request with a JSON body:

```json theme={null}
{
  "text": "New assets discovered for example.com: 2 hosts, 3 ports",
  "metadata": {
    "targetValue": "example.com",
    "hosts": "2",
    "ports": "3"
  },
  "workspaceId": "b3f1c2e4-...",
  "timestamp": "2026-10-03T09:41:22.000Z"
}
```

| Field | Type | Description |
| - | - | - |
| `text` | string | Human-readable message for the event. |
| `metadata` | object | Event-specific values used to render the message, such as the target or counts. The keys depend on the event type. |
| `workspaceId` | string | The workspace the event belongs to. |
| `timestamp` | string | ISO 8601 time the payload was sent. |

Your endpoint should return a `2xx` status. A non-`2xx` response is treated as a delivery failure and logged.

> [!NOTE]
>
> The payload shape is fixed. To attach custom headers or reshape the body, put a small adapter in front of your endpoint.

## Test

Open the integration and select **Test Integration**. OASM posts a test payload to your endpoint. Confirm your service received it and returned a success status.

## Troubleshooting

> **No payloads arrive**
>
> Confirm the URL is reachable from the OASM server, accepts `POST`, and is not blocked by a firewall or private-network restriction. If the welcome payload never arrived, the endpoint was unreachable at connect time.

> **The endpoint returns an error**
>
> OASM logs the failure but does not retry. Check the endpoint's logs for the request, and confirm it returns a `2xx` status.

> **Payloads arrive twice**
>
> Use the `timestamp` field to deduplicate on your side if your endpoint is called more than once.

## Related

> **[Notifications](/notifications)**
>
> See every event the platform produces

> **[Integrations overview](/integrations/overview)**
>
> Learn how events, secrets, and connections work

> **[Vulnerabilities](/vulnerability)**
>
> Review the findings your endpoint will receive


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.