Set Up Webhooks

Register your endpoint, secure it with signature verification, and learn the headers Rain sends with every webhook.

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. Rain treats a 3xx response as a blocked delivery and does not retry it, 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.

   Rain doesn’t permit URLs that resolve to private networks, loopback addresses (127.0.0.1), link-local addresses (169.254.x.x), or cloud metadata endpoints.

​

Webhook security and signing

Rain signs each webhook request with an HMAC SHA256 signature, based on the exact JSON payload it sends in the body. Rain includes this signature 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:

• You can select only keys with the Webhook Signing role.
• You need permission to manage API keys.
• You set the signing key 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.

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.

Node.js

import { createHmac, timingSafeEqual } from "crypto";

// rawBody: the exact request body string, before any JSON parsing.
function verifySignature(rawBody: string, header: string, signingKey: string): boolean {
  const expected = createHmac("sha256", signingKey).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(header, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

// Accept the request if either signature matches.
// Secondary-Signature is only present during key rotation.
function isRequestFromRain(
  rawBody: string,
  signatureHeader: string,
  signingKey: string,
  secondarySignatureHeader?: string,
): boolean {
  if (verifySignature(rawBody, signatureHeader, signingKey)) return true;
  return secondarySignatureHeader
    ? verifySignature(rawBody, secondarySignatureHeader, signingKey)
    : false;
}

// Call it with the values from the incoming request. Read the
// Signature and Secondary-Signature headers and pass the raw body.
const valid = isRequestFromRain(
  rawBody,
  signatureHeader,
  signingKey,
  secondarySignatureHeader,
);

​

Webhook request headers

When Rain sends a webhook to your endpoint, the request includes the following HTTP headers:

Header	Description
Content-Type	Set to application/json. The request body is formatted as JSON.
Accept	Set to application/json. Rain expects your endpoint to respond with JSON.
Signature	Contains an HMAC SHA256 signature of the request body, computed with your configured webhook signing key. Use it to verify webhook authenticity.
Secondary-Signature	Optional. Contains an HMAC SHA256 signature computed with the secondary signing key. Rain sends it during key rotation, while both keys are valid.

​

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.