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

# Netlify change integration

> Sync Netlify deploys to Flashduty On-call through Netlify deploy notifications (HTTP POST request), as change events you can correlate with alerts and incidents.

<Tip>**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/)</Tip>

Use a Netlify project's deploy notifications to sync deploys to Flashduty On-call. Each deploy becomes one Flashduty change; every notification of that deploy, from waiting for approval and building to success or failure, updates that same change.

Production deploys, branch deploys, and Deploy Previews are all sent; the `environment` label tells them apart. HTTP POST request deploy notifications are available on every Netlify plan.

<div className="hide">
  ## In Flashduty On-call

  ***

  1. In the Flashduty console, go to **Integration Center → Change Events**
  2. Select **Netlify** and enter an integration name
  3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `project` or `environment`
  4. Click **Save** and copy the generated **Push URL**
</div>

## Configure Netlify

***

Each Netlify notification listens to one event, so add one notification for each event in the table below, all with the same Push URL.

<Steps>
  <Step title="Open deploy notification settings">
    In your Netlify project, go to **Project configuration → Notifications → Deploy notifications**, click **Add notification**, and select **HTTP POST request**.
  </Step>

  <Step title="Enter the Push URL">
    1. **Event to listen for**: select one event, see the next step
    2. **URL to notify**: paste the complete Flashduty integration Push URL
    3. **JWS secret token**: leave it empty; Flashduty authenticates the request by the `integration_key` in the Push URL
    4. Click **Save**
  </Step>

  <Step title="Add one notification per event">
    | Event | Needed |
    | - | - |
    | Deploy started | Required |
    | Deploy succeeded | Required |
    | Deploy failed | Required |
    | Deploy restored | Recommended, records rollbacks |
    | Deploy request pending, Deploy request accepted, Deploy request rejected | Add these when the project requires approval for untrusted deploys |

    Deploy locked, Deploy unlocked, and Deploy deleted are not needed: they do not change a deploy's result, and Flashduty accepts them without creating a change.
  </Step>
</Steps>

## What one change is

***

| Netlify object | Change key (change\_key) | Notes |
| - | - | - |
| Deploy | The deploy ID (`id`) | Every notification of one deploy updates the same change; two deploys of the same project and branch are two changes |

A rollback (Deploy restored) publishes an existing deploy again, so it updates that deploy's change with status Done. The rollback notification carries no rollback time, so the event time is when Flashduty receives it.

## Status mapping

***

| Netlify event | Flashduty change status |
| - | - |
| Deploy request pending | Planned |
| Deploy request accepted | Ready |
| Deploy started | Processing |
| Deploy succeeded | Done |
| Deploy restored | Done |
| Deploy failed | Failed; Canceled when the build was canceled |
| Deploy request rejected | Canceled |

Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives.

## Change content

***

| Field | Content |
| - | - |
| Title | `<project name>: deploy <branch> (<short SHA>) to <deploy context>`, such as `example-site: deploy main (f95f852) to production`; a manual deploy without a branch or commit gives `<project name>: deploy to <deploy context>` |
| Description | The deploy's title, usually the commit message or the message entered for a manual deploy |
| Link | The deploy's page in the Netlify console, or the deploy's own URL when the payload has no `admin_url` |

Labels can be used in routes and to filter the change list:

| Label | Description |
| - | - |
| `project` | Netlify project name |
| `site_id` | Netlify project ID |
| `environment` | Deploy context: `production`, `deploy-preview`, `branch-deploy`, and so on |
| `ref` | The branch deployed |
| `sha` | Full commit SHA deployed |
| `deploy_id` | Netlify deploy ID |
| `review_id` | The pull request number of a Deploy Preview |
| `state` | The Netlify deploy state in the latest notification, such as `building`, `ready`, or `error` |
| `error_message` | Netlify's error message when a deploy fails |

## FAQ

***

<AccordionGroup>
  <Accordion title="Why do I only see a deploy start, or only its end?">
    Each Netlify notification sends one event. Make sure Deploy started, Deploy succeeded, and Deploy failed each have their own notification.
  </Accordion>

  <Accordion title="Does a repeated delivery record a duplicate?">
    No. When Netlify resends a notification that failed, Flashduty records it at the time of the event itself, and a notification with the same deploy, state, and time is recorded once. Deploy restored is the exception: it is recorded at the time Flashduty receives it, so a resent one is recorded again.
  </Accordion>

  <Accordion title="Why does a delivery return InvalidParameter?">
    * `unsupported X-Netlify-Event`: Flashduty received a Netlify event it does not support yet. Contact us
    * `deploy id is missing`: the payload is incomplete. Make sure the delivery comes from a Netlify deploy notification
  </Accordion>
</AccordionGroup>