> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.dev/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.
</Warning>

## Connect Webhook

<Steps>
  <Step title="Open the Applications tab">
    In the console sidebar, open **Integrations** and select the **Applications** tab.
  </Step>

  <Step title="Open Webhook">
    Select the **Webhook** card.
  </Step>

  <Step title="Enter a name and URL">
    Enter an **Integration name**, then enter the **URL** that should receive the payloads.
  </Step>

  <Step title="Choose events">
    Use the **Event** and **Severity** switches to control what OASM sends. See [What notification integrations send](/integrations/overview#what-notification-integrations-send).
  </Step>

  <Step title="Connect">
    Select **Connect**. OASM posts a welcome payload to confirm the endpoint is reachable.
  </Step>
</Steps>

## 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.

<Info>
  The payload shape is fixed. To attach custom headers or reshape the body, put a small adapter in front of your endpoint.
</Info>

## 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

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="Payloads arrive twice">
  Use the `timestamp` field to deduplicate on your side if your endpoint is called more than once.
</Accordion>

## Related

<Card icon="bell" title="Notifications" horizontal href="/notifications">
  See every event the platform produces
</Card>

<Card icon="plug" title="Integrations overview" horizontal href="/integrations/overview">
  Learn how events, secrets, and connections work
</Card>

<Card icon="shield" title="Vulnerabilities" horizontal href="/vulnerability">
  Review the findings your endpoint will receive
</Card>


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