Skip to content

Template Category Update Webhook

Also called: template_category_update · Template recategorisation webhook · Category change notification

The template_category_update webhook warns you before Meta recategorises an approved template, such as utility to marketing, and confirms once it has.

Reviewed

What is the template category update webhook?

The template category update webhook is the template_category_update field. Meta sends it when the category of one of your approved message templates is about to change, and again when it has changed. A template category decides both price and rules: in India a delivered marketing template costs ₹0.94 against ₹0.19 for utility, and marketing messages count against the per-user marketing limit. A template that quietly moves from utility to marketing can multiply what an automation costs and reduce how many people receive it.

The webhook has two shapes. The impending notice, sent before an automated recategorisation, carries correct_category (the category the template will become), new_category (confusingly, its current category) and category_update_timestamp (when the change takes effect, about 24 hours later). The completed notice, sent whether the change was automatic or manual, carries previous_category and new_category. Both include message_template_id, message_template_name and message_template_language, inside an entry whose id is the WABA.

Template recategorisation has been automatic since July 2024: Meta re-checks approved templates, and approved utility templates judged to be marketing get one day's notice — none for businesses that already have a misuse warning. A business can ask for a category review within 60 days. This differs from the template status webhook, which reports approval states such as APPROVED, REJECTED or PAUSED. Category update reports which price and rules an approved template now falls under, and always goes to the app's default callback URL.

Key takeaways

  • The template category update webhook (template_category_update) warns before Meta recategorises an approved template and confirms once it has.
  • On the impending notice, correct_category is where the template is going and new_category is its current category.
  • Automated utility-to-marketing changes get about 24 hours' notice; businesses with a misuse warning get none.
  • A category change moves price and rules: in India a marketing delivery costs ₹0.94 against ₹0.19 for utility.
  • You can request a category review within 60 days, or move promotional lines into a separate marketing template.

See InfiQ pricing

Interactive stop

Compact a category notice for your audit log

Minifying strips the whitespace people need and machines don’t, so every request is smaller.

Try

Pretty-printed JSON.

One-line event for the audit log
{"object":"whatsapp_business_account","entry":[{"id":"102290129340398","time":1760850000,"changes":[{"field":"template_category_update","value":{"message_template_id":1203456789012345,"message_template_name":"order_shipped","message_template_language":"en","correct_category":"MARKETING","new_category":"UTILITY","category_update_timestamp":1760936400}}]}]}
Bytes before
547
Bytes after
357
Saved
35%
  • 547 → 357 bytes: 35% smaller.
  • Only whitespace between tokens was removed — spaces inside strings are data and stay.
  • Minify what goes over the wire; keep the pretty version for people.
Pick a real-shaped notice — an impending change, the completed change, or a change after a category review — and see it reduced to the one-line record an audit log keeps.

Why does the template category update webhook matter?

Recategorisation is one of the few things that can change a WhatsApp bill without anyone touching a campaign. Order updates that carry a discount line, renewal reminders that read like offers, or feedback requests with a promotion attached are typical candidates. The 24-hour notice is a short window to find every automation using the template, re-forecast costs and decide whether to accept, rewrite or request a review — but only if a system is listening.

Example: A shipping update with a coupon, Bengaluru

A Bengaluru coffee brand's order_shipped utility template ends with "Use code BREW10 on your next order". On Thursday at 10:00 an impending template_category_update arrives: correct_category: MARKETING, effective Friday 10:00. The handler finds three automations using it and estimates that about 18,000 shipping notices a month would move from ₹0.19 to ₹0.94 each. The team removes the coupon line, submits order_shipped_v2 as utility, and sends the coupon only to opted-in customers in a separate marketing template.

— A shipping update with a coupon, Bengaluru

How does the template category update webhook work?

  1. Subscribe on the default callback URL

    Tick template_category_update in the app's webhook fields. Like other template webhooks it ignores WABA and phone-number overrides, so the default endpoint must handle it.

  2. Treat the impending notice as a deadline

    Read correct_category and category_update_timestamp, not new_category. Find every campaign and automation using that message_template_id and alert their owners with the deadline.

  3. Re-forecast the cost

    Multiply each automation's monthly deliveries by the new category's rate, and flag sends to users who may now hit per-user marketing limits or to markets where marketing is not delivered.

  4. Decide and act

    Accept the change, move promotional lines into a separate marketing template and submit a clean utility version, or request a category review within 60 days if Meta got it wrong.

  5. Apply the completed notice

    When previous_category and new_category arrive, update your template registry and budgets, then check pricing.category on later status webhooks to confirm deliveries are billed as expected.

The template category update webhook in code

export async function onCategoryUpdate(entry, change) {
  const v = change.value;
  const tpl = await templates.byId(v.message_template_id); // id is per language
 
  if (v.correct_category) {
    // Impending notice: new_category is the CURRENT category here.
    const effectiveAt = new Date(v.category_update_timestamp * 1000);
    const users = await automations.using(tpl.id);
    const forecast = await costs.compare(tpl.id, v.new_category, v.correct_category);
    await alerts.notify(tpl.owners, {
      template: v.message_template_name + " (" + v.message_template_language + ")",
      from: v.new_category,
      to: v.correct_category,
      effectiveAt,
      automations: users.map((a) => a.name),
      monthlyDelta: forecast.monthlyDelta,
    });
    return;
  }
 
  // Completed change: previous_category -> new_category.
  await templates.setCategory(tpl.id, v.new_category, { was: v.previous_category, at: entry.time });
  await budgets.recalculate(tpl.id);
}

Branch on correct_category: its presence marks the impending notice, where new_category still means the current category.

The template category update webhook: key facts and limits

Webhook field
template_category_update
Notice before automated change
About 24 hours (none after a misuse warning)
Impending notice fields
correct_category, new_category (current), category_update_timestamp
Completed notice fields
previous_category, new_category
Category values
MARKETING, UTILITY, AUTHENTICATION
Category review
Request within 60 days
Callback override
Not supported: always the app's default URL

Common mistakes with the template category update webhook

  • Reading new_category as the new category

    On the impending notice, new_category is the template's current category and correct_category is where it is going. Code that reads new_category sees no change and ignores the warning.

  • Handling only the completed change

    By the time previous_category/new_category arrives the change is live. React to the impending notice, which is the only moment you can still split or rewrite the template before sends are billed differently.

  • Counting on the notice always coming

    Businesses with a misuse warning get no advance notice, and manual changes arrive only as completed notices. Reconcile template categories from the API or status webhooks as a backstop.

  • Matching by name instead of ID

    One template name can exist in several languages, each with its own message_template_id. Match on the ID and language so a Hindi version's change does not relabel the English one.

Best practices for the template category update webhook

  • Keep utility templates strictly transactional: the marketing vs utility template line is drawn by content, and one promotional line can tip a template into marketing.
  • Store the full history of category changes per template; it explains past cost jumps.
  • Run a monthly report of templates whose pricing.category on status webhooks differs from your registry.
  • Give each template an owner so a recategorisation alert reaches a person, not a shared mailbox.

Template Category Update Webhook FAQs

Can I stop Meta recategorising my template?+
Not in advance, but you can request a category review within 60 days, or rewrite the content and submit it as a new template in the category you intend. Content Meta treats as mixed or unclear is categorised as marketing.
Are messages delivered before the change billed at the new rate?+
Not normally: the new category applies from category_update_timestamp, so earlier deliveries keep the old one. Confirm it from pricing.category on each message's status webhook, which records how that delivery was categorised for billing.
Does this webhook cover authentication templates?+
Rarely, because Meta does not move a misclassified authentication template to another category: it rejects it on the 1st of the following month, with no appeal. That outcome arrives through the template status webhook, not as a template_category_update.
How much notice does Meta give before recategorising a template?+
About 24 hours for an automated utility-to-marketing change. The impending notice's category_update_timestamp gives the exact effective time; businesses that already have a misuse warning get no advance notice, only the completed change.

* Per-message rates for India, ex-GST: marketing, utility and authentication effective 1 July 2026; service messages ₹0.145 since 1 October 2026 (they were ₹0 until 30 September 2026). Volume commitments earn discounts — final rate is confirmed on your account; applicable GST extra. Rates for other countries differ (see the international rate table on /pricing).

Talk to InfiQ

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms