Skip to main content
Before Rain can deliver events, register an endpoint and set up signature verification. This page covers registering your webhook URL, choosing and rotating a signing key, verifying signatures, and the headers Rain sends with each request. To learn how delivery behaves once your endpoint is live, see Webhook delivery.

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 https for any public endpoint: HMAC signatures verify integrity but do not encrypt the payload, so always use https in production to keep event data private in transit. Rain also accepts http for local sandbox testing, but never expose an http endpoint publicly. Rain does not support other protocols like ftp:// or file://.
  • 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 3xx response 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 the Signature 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, the Admin 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 Signing role can be selected.
  • You need permission to manage API keys.
  • The signing key is set per environment, on the sandbox or production Webhooks page.
See API key roles for how to create role-scoped keys.

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 a Secondary-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 the Signature header (and the Secondary-Signature header, if present). Verify the signature before processing the payload to confirm the request came from Rain.
🌧️Rain
🖥️Your endpoint
RainSign the raw body
Signed requestPOST + Signature header
Your endpointRecompute the HMAC
CompareConstant-time compare
If it matchesReturn 2xx, process
If it differsReturn 4xx, reject
Hash the raw request body exactly as received. Parsing the JSON and re-serializing it can change whitespace or key order and produce a different signature.

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.