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.

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.

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.

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

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.

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.

{
    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):

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):

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.