# Webhooks

The **Webhooks** tab in **Settings** enables you to define custom HTTP callbacks that are automatically triggered by specific deployment events—such as when a Build or CodePush operation is created, completed successfully, or fails.

<figure><img src="https://3333414532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIbwGN7KwvYi0iLbjtnXz%2Fuploads%2FxtvM4Yk4ExP8fu0oSJ1u%2Fimage.png?alt=media&#x26;token=55d64097-9e1b-4174-b0c8-cb6a12b7fc60" alt=""><figcaption></figcaption></figure>

By integrating webhooks, you can notify external systems (e.g., Slack, CI/CD pipelines, monitoring tools) in real time during various stages of the deployment lifecycle.

{% hint style="warning" %}

* Webhooks are triggered using the **HTTP POST** method.
* There is **no limit** to the number of webhooks you can add.
  {% endhint %}

## <mark style="color:red;">Adding a New Webhook</mark>

To configure a webhook:

1. Go to the **Webhooks** tab under your project’s settings.
2. Click **“+ Add Webhook.”**
3. Fill out the following fields in the form:

<figure><img src="https://3333414532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIbwGN7KwvYi0iLbjtnXz%2Fuploads%2FlDoIF6XaEYtARhgipw0s%2Fproject-webhooks-add-webhook.png?alt=media&#x26;token=641db36a-4dfc-4472-8a73-c671f2342b90" alt="" width="563"><figcaption></figcaption></figure>

#### <mark style="color:red;">Name</mark>

* The name is used solely for **display and identification purposes** within the App Maker interface.
* It does **not affect** when or how the webhook is triggered.

{% hint style="info" %}
Example: `Slack Notification`, `CI/CD Trigger`, `Build Logger`
{% endhint %}

#### <mark style="color:red;">Target URL</mark>

* Enter the **URL** that should receive the webhook request.
* If your endpoint requires **query parameters**, you can include them in the full URL.

{% hint style="info" %}
Example: `https://api.slack.com/webhook?param1=hello+world`
{% endhint %}

#### <mark style="color:red;">Events</mark>

Choose the events that will **trigger** the webhook. You can select multiple options from the list below:

<table><thead><tr><th width="297.43359375">Event</th><th>Description</th></tr></thead><tbody><tr><td><strong>Deployment Build Created</strong></td><td>Triggered when a new build is initiated</td></tr><tr><td><strong>Deployment Build Succeeded</strong></td><td>Triggered when a build completes successfully</td></tr><tr><td><strong>Deployment Build Failed</strong></td><td>Triggered when a build fails</td></tr><tr><td><strong>Deployment Build Canceled</strong></td><td>Triggered when a build is canceled</td></tr><tr><td><strong>Deployment CodePush Created</strong></td><td>Triggered when a new CodePush operation is started</td></tr><tr><td><strong>Deployment CodePush Succeeded</strong></td><td>Triggered when a CodePush operation completes successfully</td></tr><tr><td><strong>Deployment CodePush Failed</strong></td><td>Triggered when a CodePush operation fails</td></tr><tr><td><strong>Deployment CodePush Canceled</strong></td><td>Triggered when a CodePush operation is canceled</td></tr><tr><td><strong>Distribution Created</strong></td><td>Triggered when a new distribution operation to the stores is started</td></tr><tr><td><strong>Distribution Succeeded</strong></td><td>Triggered when a distribution completes successfully</td></tr><tr><td><strong>Distribution Failed</strong></td><td>Triggered when a distribution fails</td></tr><tr><td><strong>Distribution Canceled</strong></td><td>Triggered when a distribution is canceled</td></tr></tbody></table>

{% hint style="warning" %}
You can create different webhooks for each event type or group multiple events into a single webhook.
{% endhint %}

#### <mark style="color:red;">Active</mark>

Toggle this option to indicate whether the webhook is **active**.

* Only active webhooks will be triggered during event execution.
* You can deactivate a webhook at any time without deleting it.

#### <mark style="color:red;">Headers (Optional)</mark>

If the receiving service requires additional headers (e.g., authentication, content-type), you can define them here.

* Headers should be provided as key-value pairs.
* This field is **optional**, but highly useful for integrations with APIs that require tokens or specific formats.

<figure><img src="https://3333414532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIbwGN7KwvYi0iLbjtnXz%2Fuploads%2FVLhP0TXknA4EkBBcbboW%2Fproject-webhook-headers.png?alt=media&#x26;token=c0ec5740-32a8-4a82-a4ef-460b1cd8e249" alt="" width="563"><figcaption></figcaption></figure>

### <mark style="color:red;">Webhook Payload</mark>

After processing, the following data is sent as the body in webhooks triggered by the POST method.

#### Payload Data for Deployment

```typescript
{
    eventKey: string;
    status: 'succeeded' | 'failed' | 'canceled' | 'pending';
    type: 'deployment';
    os: 'ios' | 'android' | 'huawei';
    userName: string;
    projectName: string;
    tag: string;
    description: string;
    envVersion: string;
    target: 'production' | 'staging';
    deploymentId: string;
    deploymentType: 'build' | 'code-push';
    startedAt: string | null;
    completedAt: string | null;
    createdAt: string;
    issues: {
        type: 'error' | 'warning';
        message: string;
    }[]
}
```

#### Payload Data for Distribution

```typescript
{
    eventKey: string;
    status: 'succeeded' | 'failed' | 'canceled' | 'pending';
    type: 'distribution';
    storeType: 'apple-app-store' | 'google-play'; 
    userName: string;
    projectName: string;
    distributionId: string;
    startedAt: string | null;
    completedAt: string | null;
    createdAt: string;
    issues: {
        type: 'error' | 'warning';
        message: string;
    }[]
}
```

{% hint style="warning" %}
Note: The Distribution feature is still under development, so the information above may change.
{% endhint %}