Calling the Zalo API from C#/.NET: OAuth, webhooks and OA messaging

Summary: what you need to call the Zalo OA API from .NET

To call the Zalo OA API from .NET, your app must be authorised by the OA through OAuth v4 (with PKCE) to obtain an access token and refresh token, then call the OpenAPI with an access_token header. According to Zalo's documentation, access tokens are valid for 25 hours, refresh tokens for 3 months, and each refresh token can be used only once. On the .NET side, use a typed HttpClient via IHttpClientFactory, a token service with a synchronisation lock, the Microsoft.Extensions.Http.Resilience pipeline, and a webhook endpoint that verifies the signature before processing.

This article is for developers. For the business view (message types, CRM connection, customer service flow), see the Zalo OA integration guide. Endpoints and limits below come from the Zalo Platform Document Hub at the time of writing; Zalo changes its API fairly often, so check Zalo's current documentation before you ship.

OAuth v4 with PKCE: getting the first access token

Zalo's "Authentication and authorisation for apps" page describes a five-step OAuth v4 flow. The authorization code is single-use and valid for 10 minutes from issue.

• Step 1 – Create a code verifier (a 43-character string with upper case, lower case and digits, different for every request) and store it server-side. The code challenge is the SHA-256 of the verifier, Base64-encoded without padding. The Open APIs overview page says Base64URL; in .NET you can use SHA256.HashData and then Base64Url.EncodeToString (System.Buffers.Text, .NET 9 and later).
• Step 2 – In Zalo for Developers, set the callback URL and code challenge, and select the permission groups you need (for example sending messages and notifications via the OA, receiving message events).
• Step 3 – Send the authorisation link to the OA admin. After approval, your callback URL receives an HTTP GET with code and oa_id. Use the state parameter to match the code to its code verifier.
• Step 4 – POST to https://oauth.zaloapp.com/v4/oa/access_token, Content-Type application/x-www-form-urlencoded, header secret_key, body with code, app_id, grant_type=authorization_code and code_verifier.
• Step 5 – Store access_token, refresh_token and expires_in (in seconds; the documentation example is 90000, i.e. 25 hours).

Token lifecycle and safe refresh in .NET

Per Zalo's documentation: every access token comes with a refresh token; a refresh token is single-use; after a successful refresh the old refresh token is invalidated and the old access token expires as soon as the new one is issued. Refresh uses the same endpoint with grant_type=refresh_token. If the refresh token expires, the OA admin must authorise again from scratch.

The key design consequence: if two processes refresh at the same time, one ends up holding a dead refresh token. So only one place may refresh.

• Create a singleton ZaloTokenService that keeps tokens in memory and uses SemaphoreSlim so only one thread refreshes at a time.
• Persist the new token pair (encrypted database or secret store) immediately on receipt, before using the new access token. If that write fails you may lose the only valid refresh token.
• Refresh proactively before expiry (for example when a few hours remain) from a BackgroundService, instead of waiting for token errors.
• With multiple instances, use a distributed lock (for example a database lease) so only one instance refreshes; others read tokens from the shared store.
• Never put secret_key, access tokens or refresh tokens in source code, logs or error messages; load them from secret configuration via IOptions.

Typed HttpClient, retries and consultation messages

Register a typed client, for example services.AddHttpClient<ZaloOaClient>() with BaseAddress https://openapi.zalo.me/, and add .AddStandardResilienceHandler(). According to Microsoft Learn, the standard handler stacks several resilience strategies with default options to handle transient errors; use AddResilienceHandler if you need a custom pipeline. A separate DelegatingHandler fetches the access token from ZaloTokenService and adds the access_token header to each request.

Text and attachment consultation messages (tin Tư vấn) use POST https://openapi.zalo.me/v3.0/oa/message/cs with a JSON body containing recipient.user_id and message. Per the "conditions for consultation messages" page, the app must have the send-messages permission and the recipient must have interacted with the OA within 7 days. The response returns message_id, user_id, sent_time and quota information; the docs state that from 1 January 2026 consultation messages within the 48-hour window are free without limit and that some quota fields stop being returned after 1 March 2026, so do not hard-depend on them.

Proactive notifications (order confirmations, reminders) go through ZBS Template Message: POST https://openapi.zalo.me/v3.0/oa/message/template with user_id, template_id and template_data, using approved templates. For sending by phone number and ZBS account requirements, check Zalo's current documentation.

Webhooks in ASP.NET Core minimal APIs: verify before you process

Zalo POSTs events (user messages, follows, button taps) to the HTTPS webhook URL configured in your app. On the Zalo for Developers forum, the Zalo team explains that the X-ZEvent-Signature header follows mac = sha256(appId + data + timeStamp + OAsecretKey), where data is the event payload received. For the exact concatenation order, header format and timestamp source, check Zalo's current documentation and test with real events before switching to reject mode.

• Read the raw body exactly as received (enable Request.EnableBuffering or read the stream into a string) before parsing JSON; hashing re-serialised JSON will not match.
• Compute SHA256.HashData(Encoding.UTF8.GetBytes(appId + rawBody + timestamp + oaSecretKey)), convert to lower-case hex (the header value usually carries a "mac=" prefix; strip it first) and compare with CryptographicOperations.FixedTimeEquals to avoid timing leaks.
• Reject immediately (401) if the header is missing, the OA secret key is empty or the signature is wrong; unauthenticated requests must never reach business logic.
• Return 200 quickly: put the event on a queue (Channel, outbox table or message broker) and process it in a BackgroundService instead of calling AI or CRM inside the webhook request.
• Limit body size and request rate on the webhook endpoint.

Idempotency and logging without personal data

Webhooks can be delivered more than once; the Zalo forum has reports of two events for a single message. Treat every event as possibly duplicated.

• Build an idempotency key from msg_id (when present) or event_name + user_id + timestamp; store it under a UNIQUE constraint and skip events already processed.
• On the sending side, the business key from the retry section prevents duplicate sends when jobs rerun.
• Use structured ILogger logging with event_name, oa_id, idempotency key, outcome and duration; never log message content, names, phone numbers or tokens.
• If you must keep conversation content for customer service, store it in an access-controlled store with a clear retention period, separate from technical logs.

.NET libraries: write your own client or use an SDK

For the Zalo OA OpenAPI, most teams write a thin typed client: the number of endpoints is usually small, and owning the client gives control over retries, logging and token storage.

The author has an unofficial personal project, Zalo.Net, for the personal Zalo Web client, which is a different scope from this article; OA integrations should use Zalo's official OpenAPI.

Production checklist