Webhooks

Receive real-time events from NativeSuite when things happen in your app.

Setting Up a Webhook

Webhooks are configured through the dashboard:

1. Navigate to your app's settings
2. Enter your Webhook URL — an HTTPS endpoint on your server
3. NativeSuite will send POST requests to this URL when events occur

Webhook Payload

All webhook events are delivered as POST requests with a JSON body:

{
  "event": "event.type",
  "timestamp": "2026-04-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Responding to Webhooks

Your endpoint should:

1. Return a 2xx status code within 10 seconds to acknowledge receipt
2. Process the event asynchronously if it requires heavy work

If your endpoint returns a non-2xx status or times out, NativeSuite will retry the delivery with exponential backoff.

Verifying Webhook Signatures

Webhook requests are signed with the same HMAC scheme as data source requests. Verify the X-NativeSuite-Signature header to confirm the request is from NativeSuite.

Use your app's Signing Secret (not the App Secret) to verify signatures. See the Request Signing guide for implementation details.

Best Practices

• Use HTTPS — Webhook URLs must use HTTPS for security
• Respond quickly — Acknowledge the webhook with a 2xx status, then process asynchronously
• Handle duplicates — In rare cases, the same event may be delivered twice. Use the event ID for deduplication
• Verify signatures — Always verify the HMAC signature to prevent spoofed events