> 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/webhook-event-reference.md).

# Webhook Event Reference

## Webhook Event Reference

This page is the reference catalog for every event a project webhook can subscribe to, together with the exact body that is delivered to your endpoint. For how to create, edit, and activate a webhook, see [Webhooks](/tutorials/app-maker/projects/settings/webhooks.md).

### Event types

A webhook fires when a deployment or distribution operation reaches a terminal (or starting) state. There are 12 events in total, grouped below by the operation that produces them.

#### Build events

| Event                        | Fires when                      |
| ---------------------------- | ------------------------------- |
| `deployment.build.created`   | A new build is initiated.       |
| `deployment.build.succeeded` | A build completes successfully. |
| `deployment.build.failed`    | A build fails.                  |
| `deployment.build.canceled`  | A build is canceled.            |

#### CodePush events

| Event                           | Fires when                                   |
| ------------------------------- | -------------------------------------------- |
| `deployment.codePush.created`   | A new CodePush operation is started.         |
| `deployment.codePush.succeeded` | A CodePush operation completes successfully. |
| `deployment.codePush.failed`    | A CodePush operation fails.                  |
| `deployment.codePush.canceled`  | A CodePush operation is canceled.            |

#### Distribution events

| Event                    | Fires when                                   |
| ------------------------ | -------------------------------------------- |
| `distribution.created`   | A new distribution to the stores is started. |
| `distribution.succeeded` | A distribution completes successfully.       |
| `distribution.failed`    | A distribution fails.                        |
| `distribution.canceled`  | A distribution is canceled.                  |

{% hint style="info" %}
The **Events** dropdown in the webhook form currently lists the eight **deployment** events. The four `distribution.*` events are accepted by the API but are not yet shown in the interface, and the Distribution feature is still under development—so those events and their payload fields may change.
{% endhint %}

### Event key format

Every delivery carries an `eventKey` that names the exact event. The format is:

* **Deployment:** `deployment.build.{created|succeeded|failed|canceled}` and `deployment.codePush.{created|succeeded|failed|canceled}`. The `build` vs `codePush` segment reflects the deployment type.
* **Distribution:** `distribution.{created|succeeded|failed|canceled}`.

The suffix is derived from the operation's underlying status:

| Underlying status | Event suffix |
| ----------------- | ------------ |
| `pending`         | `created`    |
| `success`         | `succeeded`  |
| `failed`          | `failed`     |
| `canceled`        | `canceled`   |

{% hint style="warning" %}
The value inside the payload's `entity.status` keeps the **raw** status (for example `success`), while the `eventKey` uses the **mapped** suffix (for example `succeeded`). Match on `eventKey`, not on `entity.status`, when you route events.
{% endhint %}

### Payload envelope

Every webhook, regardless of event, delivers the same top-level envelope. The affected record is nested under `entity`—it is **not** flattened into the envelope. There is no `timestamp` or delivery `id` field.

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

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

### Delivery mechanics

Understanding how deliveries are sent helps you build a robust receiver.

* **Method:** each delivery is an HTTP `POST` with the JSON envelope as the body.
* **Headers:** `Content-Type: application/json` is always sent. Any custom headers you configured on the webhook are merged in and can override the defaults.
* **Timeout:** each request is given up to **10 seconds** to respond. Slower endpoints are treated as failed.
* **No retry:** a failed delivery (a non-2xx response, a timeout, or a connection error) is **not** retried. Failures are logged on the platform side but never re-sent, so your endpoint should not rely on redelivery.
* **No signing:** deliveries are **not** signed—there is no HMAC signature or shared secret. To verify that a request genuinely comes from App Maker, add a static authentication header (for example an `Authorization` token) in the webhook's **Headers** and check it on your endpoint.
* **Independent delivery:** when an event matches several webhooks, each is delivered concurrently and independently. One endpoint failing never blocks delivery to the others.
* **Matching:** a webhook only receives an event when it is **active** and the event is listed in its subscribed **Events**.


---

# 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/webhook-event-reference.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.