01 · Definition
What is the app secret?
The app secret is the confidential half of a Meta developer app's credentials. Every app has a public Meta App ID and a secret that only the app's administrators and servers should know. You find it under App settings → Basic in the App Dashboard, where revealing it asks you to re-enter your password. For a WhatsApp integration it does three jobs, all of which depend on it staying private.
First, Meta signs every webhook delivery with it: the X-Hub-Signature-256 header is an HMAC-SHA256 of the raw request body keyed with the app secret, and your endpoint recomputes it to prove the event came from Meta. Second, your server uses it to compute App Secret Proof (appsecret_proof), an HMAC of the access token that makes a stolen token useless without the secret. Third, it is the client_secret when you exchange an Embedded Signup or login code for an access token, and the second half of an app access token, which can be written as {app-id}|{app-secret}.
The app secret is easy to confuse with two other values. The webhook verify token is an arbitrary string you choose, which Meta sends back once in the webhook verification request and which proves nothing after that. Access tokens authorise API calls on behalf of a user or system user. The app secret is a signing key: whoever holds it can forge webhooks to your endpoint, compute valid proofs and mint app access tokens.
Key takeaways
- The app secret is the private key of a Meta developer app, paired with its public App ID.
- Meta signs every webhook delivery with it in the X-Hub-Signature-256 header, so your server needs it to verify events.
- It also computes appsecret_proof and exchanges OAuth codes for tokens, so it must never reach browser or mobile code.
- The webhook verify token is a different, arbitrary string used only in the one-time subscription handshake.
- Reset the secret if it may have leaked, and update every server that verifies signatures at the same time.
02 · Specifications
The app secret: key facts and limits
| Where to find it | App Dashboard → App settings → Basic |
|---|---|
| Signs | X-Hub-Signature-256 on every webhook POST |
| Signature format | sha256= + hex HMAC-SHA256 of the raw body |
| Also used for | appsecret_proof, OAuth code exchange, app access tokens |
| Not the same as | The webhook verify token (handshake only) |
| Where it may live | A server-side secret store only |
03 · Rationale
Why does the app secret matter?
Because the app secret both authenticates Meta to you (webhook signatures) and you to Meta (proofs and code exchange), a leak cuts both ways. An attacker can push fake inbound messages or delivery statuses into your systems, and, combined with a stolen token, can call the Graph API as your app. Keeping it in a secrets management tool, out of client code and logs, and knowing how to reset it quickly is basic hygiene for any WhatsApp integration.
04 · Operation
How does the app secret work?
Find it in the App Dashboard
Open App settings → Basic for your app and select Show next to App secret; Meta asks for your password first. Keep admin roles on the app to a few people, because app admins can view and reset it.
Store it as a server-side secret
Put it in a vault or cloud secret manager and inject it as an environment variable at runtime. It never belongs in front-end bundles, mobile apps, Git, tickets or chat messages.
Verify every webhook with it
For each POST, compute HMAC-SHA256 over the raw body with the app secret, prefix
sha256=, and compare it with theX-Hub-Signature-256header in constant time before trusting the payload.Sign outbound calls and code exchanges
Use it to compute
appsecret_prooffor Graph API calls and asclient_secretwhen exchanging an OAuth code for a token, both strictly from your backend.Reset it when exposure is suspected
Select Reset in App settings → Basic. Meta starts using the new secret, so deploy it to every service that verifies webhooks or computes proofs straight away and watch signature failures until they stop. Treat it as a fast cut-over rather than a gradual token rotation, and rehearse the switch before you need it.
05 · Code samples
The app secret in code
import hashlibimport hmacimport osAPP_SECRET = os.environ["META_APP_SECRET"].encode() # injected from your secret storedef is_from_meta(raw_body: bytes, header: str | None) -> bool:"""Verify X-Hub-Signature-256 over the exact bytes received."""if not header or not header.startswith("sha256="):return Falseexpected = hmac.new(APP_SECRET, raw_body, hashlib.sha256).hexdigest()return hmac.compare_digest(header[len("sha256="):], expected)
The app secret is the HMAC key; the raw request body is the message. Compare in constant time.
06Playground
A working model of App Secret. Use its controls to replay it step by step.
App secret or verify token: which one is this?
Compared on
App secret
Meta's signing key for your app
Webhook verify token
A string you choose for the handshake
- App secretMeta generates it with the appWebhook verify tokenYou invent it when saving the callback URL
- App secretApp settings → BasicWebhook verify tokenThe app's webhook configuration
- App secretEvery webhook POST, every appsecret_proof, code exchangesWebhook verify tokenOnly the GET subscription handshake
- App secretThe payload came from Meta and was not alteredWebhook verify tokenThe handshake request matches your configuration
- App secretWebhooks carry only HMACs of it; you send it to Meta only in server-side code exchangesWebhook verify tokenSent as-is in the hub.verify_token query parameter
- App secretForged webhooks, valid proofs, app tokens: reset nowWebhook verify tokenLow impact: change it and re-verify
Verdict
Keep both on your server, but treat only the app secret as a crown-jewel secret. Access tokens are a third thing again: they authorise API calls, while the app secret signs and proves.
Verdict: Keep both on your server, but treat only the app secret as a crown-jewel secret. Access tokens are a third thing again: they authorise API calls, while the app secret signs and proves.
07 · Cautions
Common mistakes with the app secret
Confusing it with the verify token
Checking signatures with the verify token, or answering the handshake with the secret, makes every check fail. The verify token is compared only during the GET handshake; signatures always use the app secret.
Putting it in a mobile app or front-end
Any secret shipped to a client can be extracted. Code exchange, proofs and webhook verification must all run on servers you control.
Logging it by accident
Debug dumps of environment variables, crash reports and request configs often capture secrets. Mask secret values in logging and add the secret's pattern to log and repository scanning.
Resetting without a rollout plan
After a reset, every service that verifies webhooks or computes proofs needs the new value. Update the secret store first, roll the services immediately and monitor signature failures.
08 · Recommended practice
Best practices for the app secret
- Keep the admin role on your Meta app to a few people: app admins can view and reset the secret.
- Use a separate Meta app per environment so the production secret never sits on a staging server.
- Turn on Require App Secret in the app's Advanced settings if all your Graph API calls come from servers.
- Add the secret to your secret-scanning rules so a commit containing it is blocked before it lands.
09 · Worked example: A secret found in a crash report
Example: A secret found in a crash report
During a routine log review, a Chennai logistics startup spots its production app secret printed inside a crash report sent to a third-party error tracker. The team resets the secret in App settings → Basic, updates the value in its vault, and redeploys the webhook service and the token-exchange service within minutes. A handful of webhook deliveries fail signature checks during the switch and are rejected; Meta retries failed deliveries, and the on-call engineer confirms traffic is flowing normally again. The team then adds masking for secret-like values to its error tracker and keeps staging on a separate Meta app with its own secret.
10 · Questions and answers
App Secret FAQs
- Where do I find my Meta app secret?
- In the App Dashboard under App settings → Basic. Select Show next to App secret and re-enter your password. App admins can view and reset it, so keep that role to a small group.
- Is the app secret the same as the webhook verify token?
- No. The verify token is a string you invent for the one-time subscription handshake. The app secret is Meta's signing key for every webhook delivery and must be kept confidential.
- What happens if my app secret leaks?
- Reset it straight away. Anyone holding it can forge webhook signatures to your endpoint and, with a stolen access token, compute valid appsecret_proof values or mint app access tokens for your app.
- Can I use the app secret in my mobile app?
- No. It must stay on servers you control. Have the app call your backend, which holds the secret and talks to the Graph API on the app's behalf.