• App Store
  • Alerts
  • Releases
  • Node.js
  • Backend

App Store Connect webhooks: get release alerts in Node.js

Set up App Store Connect webhooks for app version, build and TestFlight events, verify the HMAC signature in Node.js and post release alerts to Slack.

Author
Extenify Team
Published
Reading time
13 min read
A grey metal mailbox with a butterfly relief on its door, mounted on dark green wooden doors beside a sandstone wall

App Store Connect webhooks let Apple tell your server the moment something happens to your app: a version moves into review, gets approved or rejected, a build finishes processing, or a TestFlight tester sends a crash report. Before they existed, the options were refreshing App Store Connect, waiting for Apple's emails, or polling the API on a timer. Now one HTTPS endpoint can receive the event and post it wherever your team already works.

This guide covers what App Store Connect webhooks send, how they differ from App Store Server Notifications, how to create one in the web interface or through the API, a tested Node.js receiver that verifies Apple's HMAC signature and posts release alerts to Slack, how to turn Apple's ID-only payloads into readable messages, and the gaps a webhook leaves that you still need to watch.

Key takeaways

  • Webhooks arrived in App Store Connect API 4.0. Events cover app version state, build uploads, TestFlight external build state, TestFlight feedback, Apple-hosted background assets and alternative marketplaces.
  • A webhook belongs to one app, and each app can have up to ten. Creating one takes the Account Holder, Admin or App Manager role.
  • Every delivery carries an x-apple-signature header of the form hmacsha256=<hex>. Compute HMAC-SHA256 over the raw request body with your secret and compare in constant time.
  • Payloads carry IDs and states, not names or version numbers. Call the App Store Connect API to enrich them before you alert.
  • "Ready for distribution" is your status, not what users see. Storefront caches, phased releases and the ratings that follow a release still need monitoring.

What App Store Connect webhooks send

Apple added webhooks in App Store Connect API 4.0: "Use the new webhooks endpoints to setup and configure notifications for events that happen with your apps, including App version state events and TestFlight feedback events." The full list is in Apple's webhook events reference:

Event type When it fires Payload type
APP_STORE_VERSION_APP_VERSION_STATE_UPDATED An App Store version changes state, including review states appStoreVersionAppVersionStateUpdated
BUILD_UPLOAD_STATE_UPDATED A build upload changes state buildUploadStateUpdated
BUILD_BETA_DETAIL_EXTERNAL_BUILD_STATE_UPDATED An external TestFlight build changes state, such as IN_BETA_REVIEW to BETA_APPROVED buildBetaDetailExternalBuildStateUpdated
BETA_FEEDBACK_CRASH_SUBMISSION_CREATED A tester sends a crash report from TestFlight betaFeedbackCrashSubmissionCreated
BETA_FEEDBACK_SCREENSHOT_SUBMISSION_CREATED A tester sends screenshot feedback betaFeedbackScreenshotSubmissionCreated
BACKGROUND_ASSET_VERSION_* (four events) Apple-hosted background asset packs change state or get a beta release Several
ALTERNATIVE_DISTRIBUTION_* (three events) Changes for apps an alternative marketplace distributes Several

The app version event is the one most teams start with. Its payload, from Apple's documentation, looks like this:

{
  "data": {
    "type": "appStoreVersionAppVersionStateUpdated",
    "id": "7c813492-9516-4c79-903e-224effdd57ac",
    "version": 1,
    "attributes": {
      "newValue": "READY_FOR_REVIEW",
      "oldValue": "PREPARE_FOR_SUBMISSION",
      "timestamp": "2025-04-16T05:00:52.745Z"
    },
    "relationships": {
      "instance": {
        "data": { "type": "appStoreVersions", "id": "ad7e6298-2570-4ca6-b3cc-f81788e40bdc" }
      }
    }
  }
}

newValue and oldValue use Apple's AppVersionState values: PREPARE_FOR_SUBMISSION, READY_FOR_REVIEW, WAITING_FOR_REVIEW, IN_REVIEW, PENDING_DEVELOPER_RELEASE, PENDING_APPLE_RELEASE, PROCESSING_FOR_DISTRIBUTION, READY_FOR_DISTRIBUTION, REJECTED, METADATA_REJECTED, INVALID_BINARY, DEVELOPER_REJECTED, WAITING_FOR_EXPORT_COMPLIANCE, ACCEPTED and REPLACED_WITH_NEW_VERSION.

App Store Connect webhooks vs App Store Server Notifications

The names are close enough that developers mix them up, and the verification code is different, which is a common reason a signature check "never matches."

App Store Connect webhooks App Store Server Notifications V2
What they cover Your app's lifecycle: versions, builds, TestFlight, assets In-app purchases and subscriptions: renewals, refunds, expirations
Where you set them up Users and Access > Integrations > Webhooks, or POST /v1/webhooks The app's App Information page in App Store Connect
How they are signed HMAC-SHA256 of the body with your shared secret, in x-apple-signature A JWS signedPayload signed by Apple's certificate chain
Who usually handles them Release, QA and mobile teams Billing and backend teams

If you need both, run two endpoints with two verification paths. This guide is about the first column.

Step 1: Create the webhook

Apple's help page on managing webhooks sets the rules: "A webhook can only apply to one app, and you can create up to ten webhooks per app." You also "can't change the app associated with an existing webhook." The required role is Account Holder, Admin or App Manager.

In App Store Connect:

  1. Go to Users and Access and click Integrations.
  2. Under Additional, click Webhooks, then the add button.
  3. Enter a Name, the Payload URL of your endpoint and a Secret.
  4. Select the App and at least one event trigger, then click Add.

Generate the secret with something like openssl rand -hex 32 and store it with your other server secrets. You can edit the name, secret, payload URL and event triggers at any time. When you rotate the secret, have your server accept both the old and the new value for a short while, so deliveries in between still verify.

With the API: if you manage many apps, create webhooks with POST /v1/webhooks. The request needs an App Store Connect API key and a signed JWT, as described in our App Store Connect analytics API guide:

{
  "data": {
    "type": "webhooks",
    "attributes": {
      "enabled": true,
      "eventTypes": ["APP_STORE_VERSION_APP_VERSION_STATE_UPDATED", "BUILD_UPLOAD_STATE_UPDATED"],
      "name": "release-alerts",
      "secret": "<a long random string>",
      "url": "https://hooks.example.com/hooks/app-store-connect"
    },
    "relationships": {
      "app": { "data": { "type": "apps", "id": "<your app's Apple ID>" } }
    }
  }
}

The same API can list an app's webhooks (GET /v1/apps/{id}/webhooks), update one (PATCH /v1/webhooks/{id}, which can change enabled, name, url, secret and eventTypes), delete one, send a test ping and read past deliveries.

Step 2: Verify the signature in Node.js

Apple's configuration guide explains the check: "App Store Connect creates a hash signature using the secret and includes it in each POST. The signature resides in the payload header as x-apple-signature." Its example is HMAC-SHA256 of the body Hello, World! with the secret This is my secret:

x-apple-signature:hmacsha256=7f062172b01cb00b53ca068614674a3d982a34062a0f5d37687d5e3377e54657

We reproduced that value with Node's crypto module, so the scheme is plain hex HMAC-SHA256 with an hmacsha256= prefix. The receiver below uses only Node.js 22 built-ins. It verifies the raw bytes, acknowledges the delivery straight away, ignores resends of an event it already handled, and posts a readable line to Slack.

// asc-webhook.mjs: receive App Store Connect webhooks, verify them and post release alerts to Slack.
// Env: ASC_WEBHOOK_SECRET, SLACK_WEBHOOK_URL, PORT (optional)
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.ASC_WEBHOOK_SECRET;
const seen = new Set(); // use a database table in production

export function isValidSignature(rawBody, header, secret = SECRET) {
  if (!header?.startsWith('hmacsha256=')) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = header.slice('hmacsha256='.length);
  return received.length === expected.length &&
    timingSafeEqual(Buffer.from(received, 'utf8'), Buffer.from(expected, 'utf8'));
}

const LABELS = {
  WAITING_FOR_REVIEW: 'is waiting for review',
  IN_REVIEW: 'is in review',
  PENDING_DEVELOPER_RELEASE: 'was approved and is waiting for you to release it',
  PENDING_APPLE_RELEASE: 'was approved and will be released by Apple',
  PROCESSING_FOR_DISTRIBUTION: 'is processing for distribution',
  READY_FOR_DISTRIBUTION: 'is ready for distribution',
  REJECTED: 'was rejected',
  METADATA_REJECTED: 'had its metadata rejected',
  INVALID_BINARY: 'has an invalid binary',
  DEVELOPER_REJECTED: 'was pulled from review',
};

export function describe(event) {
  const { type, attributes = {} } = event.data ?? {};
  if (type === 'appStoreVersionAppVersionStateUpdated') {
    const label = LABELS[attributes.newValue];
    return label ? `App Store version ${label} (${attributes.oldValue} -> ${attributes.newValue})` : null;
  }
  if (type === 'buildUploadStateUpdated') return `Build upload is ${attributes.newState}`;
  if (type === 'buildBetaDetailExternalBuildStateUpdated') return `TestFlight external build is ${attributes.newExternalBuildState}`;
  if (type === 'betaFeedbackCrashSubmissionCreated') return 'A TestFlight tester sent a crash report';
  if (type === 'betaFeedbackScreenshotSubmissionCreated') return 'A TestFlight tester sent screenshot feedback';
  return null; // pings and event types you did not subscribe to
}

async function notify(text) {
  if (!process.env.SLACK_WEBHOOK_URL) return console.log(text);
  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ text }),
  });
}

export const server = createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/hooks/app-store-connect') {
    res.writeHead(404).end();
    return;
  }
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks); // verify the exact bytes, before JSON.parse

  if (!isValidSignature(rawBody, req.headers['x-apple-signature'])) {
    res.writeHead(401).end();
    return;
  }
  res.writeHead(200).end(); // acknowledge first, then do the slow work

  let event;
  try {
    event = JSON.parse(rawBody.toString('utf8'));
  } catch {
    return;
  }
  const id = event.data?.id;
  if (id && seen.has(id)) return; // a resend carries the same event ID
  if (id) seen.add(id);

  const text = describe(event);
  if (text) await notify(text).catch((err) => console.error('Slack post failed', err));
  else console.log('Ignored event', event.data?.type ?? 'unknown');
});

if (import.meta.url === `file://${process.argv[1]}`) {
  server.listen(Number(process.env.PORT ?? 3000));
}

We tested it locally with Apple's sample signature and a signed copy of Apple's sample payload: the valid request returned 200 and produced one Slack line, a resend of the same event ID was ignored, and requests with a wrong or missing signature returned 401.

Three details matter more than they look:

  • Raw body, not parsed JSON. If a framework parses and re-serializes the body before you hash it, spacing and key order can change and the HMAC will not match. In Express, use express.raw({ type: 'application/json' }) on this route. Our general guide to verifying webhook signatures in Node.js covers the same trap for Stripe, GitHub and Polar.
  • Constant-time comparison. timingSafeEqual throws if the buffers differ in length, hence the length check first.
  • Idempotency. Apple's help page says resending "will create a new delivery record with the same event ID." Store handled IDs in a database, not in memory, so a restart does not post the same rejection twice.

The Slack call is a single text message here. For buttons, sections and formatting, see our Slack webhook in Node.js guide.

Step 3: Test the webhook and read deliveries

In App Store Connect, open the webhook and click Test in the top-right corner. Apple sends a test delivery, and it appears under Recent Deliveries with the Ping event trigger. Through the API, the same thing is POST /v1/webhookPings with the webhook's ID. The receiver above logs and ignores the ping because describe returns nothing for it.

Recent Deliveries shows the event ID, event type, created date and status for "up to 20 of the most recent deliveries over the last week," each with a status of Success, Pending or Failed, and the request and response payloads. You can resend Failed or Success deliveries, but not test deliveries. Apple's help page documents manual resends and does not describe automatic retries, so do not assume a delivery that failed during a deploy will arrive later. A small daily job that calls GET /v1/webhooks/{id}/deliveries and alerts on any FAILED state is cheap insurance.

For local development, point a temporary webhook at a tunnel to your laptop, and delete it afterwards. Remember the ten-per-app limit.

Step 4: Turn IDs into readable alerts

A raw payload tells you that "some version" moved from IN_REVIEW to REJECTED. It does not tell you which version number, which platform or which app. One developer who built a Slack integration on these events summed it up in a Show HN post: "Apple's own webhook payloads are cryptic: event IDs and status codes, not the information you actually need."

The fix is one API call per event. The version event links to an appStoreVersions resource, which you can read with GET /v1/appStoreVersions/{id}:

// Enrich a version event with the version string and platform.
export async function versionDetails(versionId, bearer) {
  const url = new URL(`https://api.appstoreconnect.apple.com/v1/appStoreVersions/${versionId}`);
  url.searchParams.set('fields[appStoreVersions]', 'versionString,platform,appVersionState,releaseType');
  const res = await fetch(url, { headers: { Authorization: `Bearer ${bearer}` } });
  if (!res.ok) throw new Error(`App Store Connect returned HTTP ${res.status}`);
  const { data } = await res.json();
  return data.attributes; // { versionString: '3.4.0', platform: 'IOS', ... }
}

With that, the alert becomes "iOS 3.4.0 was rejected" and releaseType tells you whether an approved version will go live by itself or wait for someone to press release. Do the enrichment after you have sent the 200, as the receiver does, so a slow API call never makes Apple's delivery look failed.

Which events deserve an alert

Not every state change is worth interrupting someone. A routing that works for most small teams:

State or event Alert? Why
REJECTED, METADATA_REJECTED, INVALID_BINARY Yes, to the release owner Someone needs to fix and resubmit before the release can move
PENDING_DEVELOPER_RELEASE Yes The build is approved and waiting for a person to release it
READY_FOR_DISTRIBUTION Yes, to the wider team The release has started; this is when monitoring should begin
WAITING_FOR_REVIEW, IN_REVIEW Optional, as a quiet log Useful for measuring review time, noisy as notifications
BETA_FEEDBACK_CRASH_SUBMISSION_CREATED Yes, to the QA channel Crash reports from testers lose value quickly
Build upload COMPLETE Optional Handy if CI uploads builds unattended

Logging every state change with its timestamp also gives you a free history of how long each review took, which is useful when you plan release dates.

What webhooks do not tell you

A webhook reports what Apple's systems know about your submission. It does not report what users see, and that gap is where most post-release surprises happen.

  • Ready for distribution is not visible everywhere. The public listing and the iTunes Search API can lag behind a release by hours, and the new version reaches storefronts and devices over time. Check the public version per country rather than assuming.
  • The ratings that follow a release. No webhook fires when your rating drops or a wave of one-star reviews arrives. That is what you want to know in the first days after a release; our checklist of what to watch after a release applies to apps as well as extensions, and the AI-written App Store review summary on your product page changes with those reviews.
  • Other stores and other apps. Webhooks cover your own apps on Apple's platforms only. Your Google Play listing and your competitors' releases need a different source.

For the public side, Extenify is an app store analytics dashboard that checks your App Store and Google Play listings once a day and alerts you to new versions, rating drops, rating count swings and new reviews by email, Slack, Discord, Telegram or Teams. It reads the public listing, so it shows when a version actually appears in the store, and it works the same way for competitors' apps and for Chrome, Edge and Firefox extensions. Combined with webhooks, you get Apple's internal status as it changes and the public result the next day. See Extenify pricing for the free trial. If you want a full version timeline of any app, our guide to App Store version history shows how to build one.

App Store Connect webhooks checklist

  • Create one webhook per app with a long random secret, using an Admin or App Manager account.
  • Subscribe only to the events you will act on; start with app version state and TestFlight crashes.
  • Verify x-apple-signature over the raw body with HMAC-SHA256 and a constant-time comparison.
  • Return 200 quickly and do enrichment and Slack posts afterwards.
  • Store handled event IDs so resends do not alert twice.
  • Send a test ping and confirm it under Recent Deliveries.
  • Check deliveries daily for FAILED and resend if needed.
  • Keep public listing, rating and review monitoring for after READY_FOR_DISTRIBUTION.

Frequently asked questions

Does App Store Connect have webhooks?

Yes. App Store Connect API 4.0 added webhooks for app version state changes, build uploads, TestFlight external build state, TestFlight crash and screenshot feedback, Apple-hosted background assets and alternative marketplace events. You can set them up under Users and Access > Integrations > Webhooks or with POST /v1/webhooks.

How do I verify the x-apple-signature header?

Compute HMAC-SHA256 over the exact raw request body using the secret you entered when you created the webhook, encode it as lowercase hex, and compare it with the part of the header after hmacsha256=. Use a constant-time comparison. Apple's sample, the body Hello, World! with the secret This is my secret, produces 7f062172b01cb00b53ca068614674a3d982a34062a0f5d37687d5e3377e54657.

Why does my App Store Connect webhook signature not match?

The usual causes are hashing a parsed and re-serialized body instead of the raw bytes, using a different secret than the one saved in App Store Connect, forgetting to strip the hmacsha256= prefix, or verifying with App Store Server Notifications code, which uses signed JWS payloads instead of HMAC.

How many webhooks can an app have?

Up to ten, according to Apple's help page. Each webhook belongs to a single app, and you cannot move a webhook to a different app; create a new one instead.

Can I get an App Store Connect webhook when my app is approved?

Yes. Subscribe to APP_STORE_VERSION_APP_VERSION_STATE_UPDATED. An approval shows up as a change to PENDING_DEVELOPER_RELEASE (manual release) or PENDING_APPLE_RELEASE, followed later by READY_FOR_DISTRIBUTION when the version goes live.

Summary

App Store Connect webhooks replace polling with a push: create one per app, pick the events you care about, and Apple posts each change to your HTTPS endpoint with an x-apple-signature HMAC you can verify in a few lines of Node.js. Verify the raw body, acknowledge fast, ignore duplicate event IDs, and enrich the ID-only payloads with one API call before you alert. Then keep watching the public side, because the moment Apple says a version is ready for distribution is when users, ratings and reviews start to move.

Image credits

Put every store in one dashboard tonight.

Sign in with Google, paste one store link, and your unified view is live in under a minute. Then 7 days of Pro free, no credit card required, and you never touch your app's code.

Start free trial