---
title: Event Mappings
summary: >-
  The Audit Log Event Mappings API lets you configure which Fastly audit log
  events trigger notifications to your integrations. An event mapping links one
  or more event types to one or more notification integrations, scoped to your
  account, specific CDN services, Compute services, or Next-Gen WAF workspaces.
  Use the event-types and scope-types discovery endpoints to retrieve the full
  list of supported event and scope types before creating mappings. All
  endpoints require the <code>superuser</code> role.
url: >-
  https://www.fastly.com/documentation/reference/api/observability/notifications/event-mappings
---

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `description` | string | An optional description of the mapping. |
| `event_types` | array | The audit event types that trigger a notification. Each event type must be valid for the given <code>scope_type</code>. Use the <code>event-types</code> endpoint to retrieve the supported values. |
| `integration_ids` | array | The IDs of the integrations that should receive notifications. Must reference integrations for the account linked to the supplied token. |
| `name` | string | A descriptive name for the mapping. |
| `scope_ids` | array | The specific service or workspace IDs to scope this mapping to. Omit or provide an empty array to apply the mapping to all resources of the given scope type. Must be empty or omitted when <code>scope_type</code> is <code>account</code>. |
| `scope_type` | string | The category of Fastly resource a mapping applies to.  <code>account</code>: applies account-wide, regardless of any specific service or workspace. - <code>vcl</code>: applies to specific CDN (VCL) services identified by service ID. - <code>wasm</code>: applies to specific Compute (Wasm) services identified by service ID. - <code>ngwaf</code>: applies to specific Next-Gen WAF workspaces identified by workspace ID. Some event types are compatible with more than one scope type. For example, <code>ngwaf.list.create</code> can be mapped at either <code>account</code> scope (fires for any matching event across the account) or <code>ngwaf</code> scope (fires only for specified workspaces). Use the <code>event-types</code> endpoint to see which scope types each event supports. |
| `limit` | integer | The maximum number of results returned per page. |
| `next_cursor` | string | Cursor value to retrieve the next page of results. Pass this as the <code>cursor</code> parameter in your next request using the same filter and sort values. Omitted when the results are the last page. |
| `previous_cursor` | string | Cursor value to retrieve the previous page of results. Omitted when the results are the first page. |
| `sort` | string | The sort order applied to the results. |
| `total` | integer | Total number of event mappings matching the filters. |
| `created_at` | string | Timestamp when the mapping was created. (Read-only) |
| `customer_id` | string | The ID of the customer this mapping belongs to. (Read-only) |
| `id` | string | Unique identifier for the mapping. (Read-only) |
| `mapping_status` | string | Indicates whether the mapping is permitted to send notifications. This field is set server-side and cannot be set directly. A mapping is <code>active</code> when it has at least one integration ID. It becomes <code>inactive</code> automatically when all of its integration IDs are removed — for example, when an integration is deleted. An inactive mapping does not send notifications. |
| `updated_at` | string | Timestamp when the mapping was last updated. (Read-only) |
| `meta` | object | Metadata about the filter results. |
| `display_name` | string | A human-readable name for the event type. |
| `event_type` | string | The event type identifier. Use this value in the <code>event_types</code> field when creating a mapping. |
| `scope_types` | array | The scope types this event type is compatible with. |

## API endpoints

### List supported event types

**GET** `/notifications/v1/event-mappings/event-types`

Returns all audit event types that can be used when creating an event mapping. Use the optional <code>scope_type</code> parameter to filter the list to event types that are compatible with a specific scope. Results are sorted alphabetically by <code>event_type</code> by default. Use <code>sort=-event_type</code> to reverse the order.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `scope_type` | string | query | No | Filter results to the given scope type. Must be one of the values returned by the <code>scope-types</code> endpoint. |
| `sort` | string | query | No | Sort event types alphabetically. Use <code>event_type</code> for ascending order or <code>-event_type</code> for descending order. |

### List supported scope types

**GET** `/notifications/v1/event-mappings/scope-types`

Returns all scope types supported by the Event Mappings API. A scope type defines the category of Fastly resource that a mapping applies to. Results are sorted alphabetically by <code>scope_type</code> by default. Use <code>sort=-scope_type</code> to reverse the order.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `sort` | string | query | No | Sort scope types alphabetically. Use <code>scope_type</code> for ascending order or <code>-scope_type</code> for descending order. |

### List event mappings

**GET** `/notifications/v1/event-mappings`

Returns event mappings matching the given filters. If no filters are specified, returns all event mappings for the account linked to the supplied token, sorted by creation date ascending. Results are paginated using cursor-based pagination.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `cursor` | string | query | No | Cursor value from the <code>next_cursor</code> field of a previous response, used to retrieve the next page. To request the first page, this should be empty. |
| `integration_id` | string | query | No | Filter results to mappings that reference the given integration ID. |
| `limit` | integer | query | No | Limit how many results are returned. |
| `mapping_status` | string | query | No | Filter results by mapping status. |
| `name` | string | query | No | Filter results to mappings whose name contains the given string (case-insensitive). |
| `scope_id` | string | query | No | Filter results to mappings that apply to the given service or workspace ID. Cannot be combined with <code>scope_type=account</code>. |
| `scope_type` | string | query | No | Filter results to the given scope type. Must be one of the values returned by the <code>scope-types</code> endpoint. |
| `sort` | string | query | No | Sort the results by creation date. Use <code>created_at</code> for ascending order (oldest first) or <code>-created_at</code> for descending order (newest first). |

### Create an event mapping

**POST** `/notifications/v1/event-mappings`

Creates an event mapping. The mapping becomes active immediately.
<code>integration_ids</code> must reference integrations for the account linked to the supplied token. <code>event_types</code> must be valid for the given <code>scope_type</code>. Use the <code>event-types</code> endpoint to confirm compatibility.
For <code>scope_type</code> values other than <code>account</code>, the <code>scope_ids</code> parameter can be provided to restrict the mapping to specific services or workspaces. An empty <code>scope_ids</code> array means the mapping applies to all resources of that scope type.

### Get an event mapping

**GET** `/notifications/v1/event-mappings/{mapping_id}`

Retrieves an event mapping by ID.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `mapping_id` | string | path | Yes | The ID of the event mapping. |

### Update an event mapping

**PUT** `/notifications/v1/event-mappings/{mapping_id}`

Replaces an event mapping. All fields must be provided. Omitted fields are not preserved from the previous version.
<code>integration_ids</code> must be non-empty. A mapping is always set to <code>active</code> on update.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `mapping_id` | string | path | Yes | The ID of the event mapping. |

### Delete an event mapping

**DELETE** `/notifications/v1/event-mappings/{mapping_id}`

Deletes an event mapping.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `mapping_id` | string | path | Yes | The ID of the event mapping. |