> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/tutorials/app-maker/projects/settings/webhooks.md).

# Webhooks

## 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="/files/uLNXSxJvh6bYVIT9bd5v" 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="/files/oFy1eyasxkbQabnRozsu" alt=""><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.

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

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

Every webhook shares the same **envelope**; the affected record is nested under `entity`:

```typescript
{
    eventKey: string;                       // e.g. "deployment.build.succeeded"
    type: 'deployment' | 'distribution';
    projectName: string;
    entity: { /* the full deployment or distribution record — key fields below */ };
}
```

**`eventKey`**

`eventKey` identifies the exact event. Its format is:

* **Deployment:** `deployment.build.{created|succeeded|failed|canceled}` and `deployment.codePush.{created|succeeded|failed|canceled}`
* **Distribution:** `distribution.{created|succeeded|failed|canceled}`

The record's raw status maps to the event suffix as: `pending → created`, `success → succeeded`, `failed → failed`, `canceled → canceled`.

**`entity` for Deployment (`type: 'deployment'`)**

Key fields (the full deployment record is included; additional internal fields may also be present):

```typescript
entity: {
    _id: string;
    status: 'pending' | 'deploying' | 'success' | 'failed' | 'canceled';
    os: 'ios' | 'android' | 'huawei';
    deploymentType: 'build' | 'code-push';
    tag: string;
    description?: string;
    startedAt?: string | null;   // ISO 8601
    completedAt?: string | null; // ISO 8601
    createdAt?: string;          // ISO 8601
    issues?: {
        type: 'error' | 'warning';
        message: string;
    }[];
    // …plus the remaining fields of the deployment record
}
```

**`entity` for Distribution (`type: 'distribution'`)**

Key fields (the full distribution record is included; additional internal fields may also be present):

```typescript
entity: {
    _id: string;
    status: 'pending' | 'uploading' | 'uploaded' | 'success' | 'failed' | 'canceled';
    storeStatus?: string;
    track?: string;
    releaseMethod?: string;
    startedAt?: string | null;   // ISO 8601
    completedAt?: string | null; // ISO 8601
    createdAt?: string;          // ISO 8601
    issues?: {
        type: 'error' | 'warning';
        message: string;
    }[];
    // …plus the remaining fields of the distribution record
}
```

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.akinon.com/tutorials/app-maker/projects/settings/webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.