Skip to main content
Webhook forwarding lets Nango receive webhooks from external APIs and forward them to your app’s webhook URL. Use it when your app should own the webhook handling logic, but you still want Nango to provide the provider-specific webhook URL, routing, signing, retries, and logs. For processing the webhook inside Nango function code, use webhook functions.

​
How forwarding works

  1. You configure your app’s webhook URL in Environment Settings > Webhook URLs.
  2. You register the integration’s Nango webhook URL in the provider’s developer portal. Find it in Integrations > [Integration] > Webhooks.
  3. The provider sends a webhook to Nango.
  4. Nango runs the provider-specific routing logic and tries to map the event to one or more Nango connections.
  5. Nango forwards the payload to your app’s webhook URL and signs the request like other Nango webhooks.
Nango forwards webhooks asynchronously after accepting the provider webhook, so slow app endpoints do not block the provider response.

​
Forwarded payloads

When Nango can attribute the webhook to a connection, your app receives a Nango wrapper:
If a provider webhook maps to multiple connections, Nango sends one forwarded webhook per connection. If Nango cannot map the webhook to a connection, Nango forwards the raw provider payload without the wrapper. Your consumer should handle both shapes when the provider can emit unattributed events.

​
Headers and signatures

Nango forwards safe provider headers when possible, excluding headers that should not be replayed such as authorization, cookie, host, content-length, content-type, user-agent, and similar transport-sensitive headers. Every forwarded webhook is signed with the same headers used by other Nango webhooks:
  • X-Nango-Hmac-Sha256
  • X-Nango-Signature for backwards compatibility
Verify forwarded webhooks the same way you verify other webhooks from Nango. See Verifying webhooks from Nango.

​
Unverified webhooks

Nango verifies the provider signature before forwarding whenever the provider signs its webhooks and the integration has the secret to check it. When Nango knows it skipped that check, for example because the webhook secret is not set on the integration, it still forwards the webhook but flags it:
  • The X-Nango-Webhook-Unverified: true header is set on the forwarded request, including raw payloads.
  • The Nango wrapper includes "unverified": true.
The flag is only set when the integration’s webhook handling knows verification was skipped. A forward without it is not a guarantee that the provider signature was checked. Some integrations, such as the unauthenticated provider, never verify. The Nango signature on flagged requests only proves the webhook came through Nango, not that the provider sent it. Anyone who knows the integration’s webhook URL can send one. Treat the payload as untrusted, and set the webhook secret on the integration to enable verification. The forward operation in the Nango logs also shows a warning with the reason.

​
When to use forwarding

Use forwarding when:
  • Your app already has webhook handling logic.
  • You want app code to decide what to do with the provider event.
  • You need Nango to attribute the event to a connection when possible.
  • You want webhook delivery logs and retries without running Nango function code.
Use webhook functions when Nango should update records, normalize the payload, or run connection-scoped integration logic immediately.

​
Configure forwarding

1

Configure your app webhook URL

In Nango, open Environment Settings > Webhook URLs and add your app’s endpoint.Nango sends forwarded webhooks to the same URLs used for auth, sync, and async action webhooks.
2

Register the provider webhook URL

In the integration page, copy the Nango webhook URL from Integrations > [Integration] > Webhooks and register it in the provider’s developer portal.Some providers use one global webhook registration. Others require one webhook registration per connected account. Provider-specific docs explain the required setup.
3

Handle both payload shapes

If the payload has "type": "forward", read connectionId, providerConfigKey, and payload.If the payload does not have "type": "forward", handle it as the raw provider payload. This can happen when the provider event cannot be attributed to a Nango connection.
When implementing webhook forwarding, first find the provider-specific Nango webhook guide. Confirm whether the provider routes automatically or requires embedding the Nango connection ID, tenant ID, team ID, installation ID, or another identifier in the provider webhook subscription.Implement signature verification with X-Nango-Hmac-Sha256, then branch on whether the incoming body has type: "forward". Store and use connectionId only when it is present.

​
Providers that do not sign webhooks

Affinity, Fillout and ShipStation do not sign their webhooks, so Nango checks a secret you choose for each connection instead. Nango rejects a webhook unless it carries the secret of the connection it is routed to.
  1. Generate a random secret of at least 16 characters per connection and store it as webhookSecret in that connection’s metadata.
  2. Send that connection’s secret with every webhook registered for it, in the X-Nango-Webhook-Secret header or, when the provider only lets you set a URL, as a nangoWebhookSecret query param on the Nango webhook URL.
Prefer the header when the provider supports custom headers (Fillout, ShipStation v2). Affinity and ShipStation v1 only take a URL. Nango removes the secret before the webhook reaches your functions or your app. Affinity’s payload does not say which connection it is for, so also add nangoConnectionId=<CONNECTION-ID> to the webhook URL registered in each end user’s Affinity instance. The secret usually sits in your end user’s own webhook config, where their admins can see it. Because it belongs to one connection, it only lets them send events for their own connection. Salesforce events come from an Apex trigger you install in each connected org, and use the same per-connection secret. See How to set up webhooks with Salesforce on Nango.

​
Retries and debugging

Nango retries forwarded webhooks when your app returns a non-2xx response or has a network failure. Forwarded attempts appear in Nango logs as webhook forwarding operations. For retry behavior, timeout limits, and local testing tips, see Webhook retries & debugging and Webhook limits.