How to Build a Webhook API for Your SaaS
How Webhooks Fit Into a SaaS Product
Most SaaS products need to receive data from external services at some point. Common webhook use cases include:
- Payment notifications: Stripe or PayPal sends a webhook when a payment succeeds, fails, or is disputed
- Email delivery events: Your email provider sends webhooks for opens, clicks, bounces, and complaints
- Form submissions: An external form builder sends submitted data to your webhook URL
- CRM updates: When a contact is updated in an external CRM, it pushes the change to your app
- IoT and sensor data: Connected devices send data readings to your webhook endpoint
- Third-party integrations: Any service that supports webhooks can push data to your SaaS
How the Mode System Works
The platform routes incoming webhook requests through the mode system. A mode is a URL pattern that maps to a handler function in your app. The URL structure is:
https://api.aiappsapi.com/{accountID}/{app}/{mode}/{data1}/{data2}
When an external service sends a request to this URL, the platform loads your app code and calls the handler function associated with that mode. Your function receives the account ID, the URL path segments, and the full request body. You can process the data, update the database, trigger workflows, or return a response.
This means each webhook type gets its own URL. A payment webhook goes to one mode, an email event webhook goes to another, and a form submission webhook goes to a third. Each has its own handler function with its own processing logic.
Building a Webhook Endpoint
Add an entry to your appModes configuration with the mode name and the function to call. The mode name becomes part of the URL, so choose something descriptive like "paymenthook" or "formsubmit".
Your function receives the incoming request data. Parse it according to the external service's format, validate that it is legitimate (check signatures if the service provides them), and process the data.
Configure the external service to send webhooks to your mode URL. Include the account ID in the URL so your handler knows which customer the data belongs to.
External services typically retry failed webhook deliveries. Return a 200 status for successful processing. If your handler fails, the service will retry, so make sure your processing is idempotent (safe to run multiple times with the same data).
Webhook Security
Since webhook URLs are publicly accessible, you need to verify that incoming requests actually come from the expected service. Common verification methods:
- Signature verification: Most services sign webhook payloads with a secret key. Verify the signature before processing.
- IP allowlisting: Some services publish the IP addresses they send webhooks from. You can check the source IP.
- Shared secret: Include a secret token in the webhook URL or headers that only you and the external service know.
Outgoing Webhooks for Your Customers
If your SaaS customers need to receive notifications when events happen in your product (like a new order, a status change, or a threshold being reached), you can also send outgoing webhooks. Your code makes an HTTP POST request to a URL that your customer configures in their account settings, delivering event data in real time.
This is how many SaaS products enable integrations without building specific connectors for every external tool. Customers configure their own webhook URLs and connect your product to whatever systems they use.
Build webhook endpoints for your SaaS with the mode system. Receive payment events, form data, and external integrations easily.
Get Started Free