Overview
Every webhook sent to the iPaaS.com Webhook Receiver must carry your subscription's Webhook API Key as a token. The recommended method is a Token header. A URL-encoded token in the webhook URL is also common and fully supported, as is a token in the request body. The receiver uses this token to identify which company and subscription the webhook belongs to. Webhooks without a valid token are rejected and never reach the Events Queue.
Use this article when you configure an external system to send webhooks to iPaaS.com, or when you share setup instructions with a client or partner.
Why iPaaS.com Requires a Webhook Token
The iPaaS.com Webhook Receiver is a shared, multi-tenant endpoint. Many companies and subscriptions send webhooks to the same URL, so the receiver needs a reliable way to know who each webhook belongs to and whether it can be trusted. The token provides both.
Routing: The token identifies the exact company and subscription the webhook is for, so the event is processed against the right data and mappings.
Authentication: Requests without a valid token are rejected. This blocks spoofed or unsolicited traffic from creating, updating, or deleting records in a customer's systems.
Data integrity: Because webhooks can trigger orders, inventory, and customer changes downstream, only verified senders are allowed to start those transfers.
Why a header is recommended: A header keeps the secret out of the endpoint URL, where it could be exposed in server logs, proxies, or browser history. That said, a URL-encoded token in the URL is common and fully supported, especially for systems that let each user enter their own webhook URL but cannot add custom headers.
What We Ask of Technology Partners
To integrate with iPaaS.com via webhooks, the sending system must be able to include the customer's token with each outbound webhook, sent over HTTPS. Any of these methods works:
Recommended: A custom static header (key and value), configurable per webhook or per account so each customer can enter their own token.
Supported: A URL-encoded token in a per-user webhook URL, for systems that do not support custom headers.
Supported: A token field in the request body.
If your system can only use options 2 or 3, your webhooks are still supported.
Signed webhooks: Some systems authenticate webhooks only with a signature (for example, an HMAC signature header) rather than a token. iPaaS.com cannot verify signed webhooks by default. Support can sometimes be added for a specific integration, so raise this early when planning the integration.
Polling as a fallback: If a system cannot send webhooks with a token in any of these ways, iPaaS.com can still integrate with it by polling. On a set schedule, iPaaS.com calls the system's API to check for new or changed records. Polling works without any webhook configuration, but changes arrive on the polling interval rather than in real time, so webhooks remain the preferred option where supported.
Required Values
Every webhook needs a token and a scope. Where each value goes depends on what the sending system supports and how the integration is configured.
Value | Where it can go | Notes |
Token |
| The subscription's Webhook API Key, pasted as-is (no |
Scope |
| The iPaaS.com scope for the event, for example |
Content-Type | Header | Usually |
Some integrations accept a different authentication format for their own receiver endpoints. Always follow the integration-specific installation article when one exists.
Configure the Webhook in the Sending System
Open the webhook settings in the external system and create a new webhook (or endpoint).
Enter the iPaaS.com receiver URL from the integration's installation article. Dynamic receivers follow the pattern
https://api.ipaas.com/HookApi/v2/dynamic/{integration}.Select the events you want to send to iPaaS.com.
Add a custom header with Key
Tokenand Value set to your Webhook API Key (or place the token where the integration's article specifies).Add a
Scopeheader if the scope is not already sent in the request body.Save the webhook, then trigger a test event (for example, update a test record).
In iPaaS.com, confirm the hook appears in the Events Queue with the expected scope.
Example Request
POST https://api.ipaas.com/HookApi/v2/dynamic/{integration}
Token: {your Webhook API Key}
Scope: customer/updated
Content-Type: application/json{ "id": "12345", "event": "customer.updated" }Troubleshooting
Symptom | Likely cause | Fix |
Webhook rejected or returns 401 | Token missing, misspelled, or holds the wrong key | Re-copy the Webhook API Key from the correct subscription and re-save it in the sending system |
Hook never appears in the Events Queue | Key belongs to a different subscription or environment | Confirm the key matches the subscription that should process the hook |
Hook appears with the wrong data type | Scope missing or incorrect in the header or body | Set the scope that matches the event, per the integration's article |
Worked before, now failing | Webhook API Key was reset by iPaaS.com support | Copy the new key and update the token everywhere the old key was used |
Security Notes
Treat the Webhook API Key like a password. Share it only through secure channels, never in tickets or email threads.
Send webhooks over HTTPS only.
If a key is exposed, contact iPaaS.com support to have it reset, then update every sending system. Self-service key regeneration is not currently available.