Skip to main content

How it works

  1. WooCommerce sends a POST request to your Nango webhook URL when a subscribed store event occurs, for example order.created.
  2. Nango looks up the connection named by the nangoConnectionId query param on the webhook URL and verifies the delivery’s X-WC-Webhook-Signature against that connection’s own webhook secret.
  3. Nango routes the event to that connection, using the X-WC-Webhook-Topic header as the webhook type.
Every WooCommerce store is its own connection and sets its own webhook secret, so each connection needs its own webhook in the store and its own webhookSecret in Nango. Deliveries without a valid signature are rejected.

Setup

1. Get your Nango webhook URL

In the Nango dashboard, open your WooCommerce integration and copy the Webhook URL. Append ?nangoConnectionId=<CONNECTION-ID> for the connection you are registering the webhook for. URL-encode the connection ID if it contains characters like /, : or spaces.

2. Pick a webhook secret

Generate a random secret for the connection, for example with openssl rand -hex 32. You use the same value in the store and in Nango.

3. Register the webhook in WooCommerce

  1. In the WordPress admin, go to WooCommerce → Settings → Advanced → Webhooks and select Add webhook.
  2. Set Status to Active and pick a Topic, for example Order updated.
  3. Set Delivery URL to the URL from step 1.
  4. Set Secret to the secret from step 2.
  5. Save. WooCommerce pings the URL once, and Nango answers it without routing anything.
Repeat for every topic you want to receive.

4. Set the webhook secret in Nango

Store the same secret as webhookSecret in the connection’s metadata:
See Update connection metadata for the full reference.
The webhook secret on the integration’s Settings page is not used for WooCommerce. Nango only verifies against the connection’s webhookSecret.
WooCommerce disables a webhook after more than 5 consecutive failed deliveries. If the secrets don’t match, every delivery is rejected and the webhook ends up disabled. Fix the secret, then set the webhook back to Active.

Handle the webhook

Once routed, you have two options:
  • Forward it to your app: Nango forwards the event to your webhook URL with connection attribution. See External webhook forwarding.
  • Process it in a sync: run a sync when the webhook arrives using webhookSubscriptions and onWebhook. Subscribe to topics like order.updated or product.deleted. See Real-time syncs.

Rollback strategy

Delete the webhook in WooCommerce → Settings → Advanced → Webhooks, or with the API:
Then clear webhookSecret from the connection’s metadata.
Need help getting started? Join us in the community.