Set up webhooks
1
Add your webhook URL
In your developer dashboard, add a webhook URL. Once configured, Rain sends webhook events to the specified URL whenever relevant actions occur.Your webhook URL must:
- Use
httpsfor any public endpoint: HMAC signatures verify integrity but do not encrypt the payload, so always usehttpsin production to keep event data private in transit. Rain also acceptshttpfor local sandbox testing, but never expose anhttpendpoint publicly. Rain does not support other protocols likeftp://orfile://. - Resolve to a public IP address: Rain blocks URLs that resolve to private, internal, or reserved IP addresses.
- Respond directly, without redirecting: Rain does not follow HTTP redirects when it delivers events. A
3xxresponse is treated as a blocked delivery and is not retried, so point the URL at the endpoint that handles the event.
2
Pass URL validation
Rain validates your URL when you register it. If your URL does not meet these requirements, registration fails with a
400 Bad Request error.URLs that resolve to private networks, loopback addresses (127.0.0.1), link-local addresses (169.254.x.x), or cloud metadata endpoints are not permitted.
Webhook security and signing
Each webhook request is signed using an HMAC SHA256 signature, based on the exact JSON payload sent in the body. This signature is included in theSignature HTTP header of the request.
Rain uses one of your tenant API keys as the HMAC secret. This is the same kind of key you use in the Api-Key header for API requests. Use the full key value (the secret you copied when that key was created) when you verify signatures.
Choose a signing key
By default, theAdmin API key that Rain creates with your tenant is also the webhook signing key. For better separation of concerns, create a dedicated signing key from the API Settings page in the dashboard. A few rules apply:
- Only keys with the
Webhook Signingrole can be selected. - You need permission to manage API keys.
- The signing key is set per environment, on the sandbox or production Webhooks page.
Rotate signing keys
To rotate keys without downtime, use the key rotation API endpoints: create a secondary key, then promote it to the primary signing key. During rotation, Rain also sends aSecondary-Signature header while both keys are still valid.
To delete an API key that is currently your primary or secondary webhook signing key, first set a different signing key in the dashboard, then delete the old key.
Verify a signature
Compute the HMAC SHA256 of the exact request body using your signing key, then compare it to theSignature header (and the Secondary-Signature header, if present). Verify the signature before processing the payload to confirm the request came from Rain.
Webhook request headers
When Rain sends a webhook to your endpoint, the request includes the following HTTP headers:What’s next
Webhook delivery
Learn the event lifecycle and how to respond, plus ordering, retries, and versioning.
How webhooks work
Browse every event category and find a specific event.