Webhooks

​

When to use webhooks

• Real-time CRM sync. A donor finishes a stock gift → their CRM record updates in seconds.
• Automated receipting and acknowledgments. Contribution approved → trigger your thank-you email pipeline.
• Finance and reconciliation automation. Deposit paid out → ping your accounting workflow.
• Recurring gift recovery. Recurring gift failed → enroll the donor in a dunning sequence.
• Internal dashboards and alerts. Pipe events into Slack, Datadog, or internal tooling.
• No-code automation. Wire your endpoint to Zapier, Make, n8n, or any HTTP listener.

​

Event catalog

​

Contributions

​

Donors

​

Recurring gifts

​

Deposits

​

Wildcard

​

Create a subscription

​

Verify webhook signatures

​

Example verification (Node.js)

import crypto from "node:crypto";

export function verifyOverflowSignature(req, secret) {
  const signature = req.headers["x-overflow-webhook-signature-hmacsha256"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody) // Buffer or string of the exact bytes received
    .digest("hex");

  // Use timing-safe comparison
  const a = Buffer.from(signature ?? "", "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

​

Rotate the signing secret

• Immediately
• 1 hour
• 6 hours
• 12 hours
• 24 hours
• 72 hours
• 1 week

​

Retries and delivery guarantees

​

Delivery health notifications

• Webhook deliveries failing — the endpoint is unhealthy, retries may still be in progress, and the subscription is still enabled.
• Webhook subscription disabled — Overflow auto-disabled the subscription after a terminal delivery failure. Deliveries have stopped until someone re-enables it.

​

Failing email cadence

​

When Overflow auto-disables a subscription

• A non-retriable HTTP response (most 4xxs), or
• A retriable failure that has exhausted the retry budget (up to 16 attempts over the multi-day backoff).

​

What to do when you receive one

1. Open the link in the email and review recent attempts on the Event Deliveries tab (status, response body, timing).
2. Fix the endpoint (uptime, auth, URL, TLS) — or temporarily Disable the subscription if you are not ready to receive traffic.
3. If you received the disable email, re-enable the subscription from the dashboard once the endpoint is healthy.
4. Use Send Test Event to confirm the receiver before relying on live traffic again.

​

View deliveries and resend

​

Send a test event

• They include the header x-overflow-webhook-test: true and an event ID prefixed evt_test_....
• They are not retried and not stored in the delivery log.

​

Manage subscriptions

• Edit: change the name, description, URL, or event selection. Edit cannot change a subscription’s status; use Enable / Disable instead.
• Enable / Disable: pause or resume delivery without losing config or history.
• Send Test Event: fire a synthetic payload to validate the endpoint.
• Delete: soft-delete the subscription. It is archived rather than destroyed; it no longer receives events and is removed from the list.

​

Quickstart

​

Glossary

• Webhook: an HTTP POST that Overflow sends to your server when something happens in your account.
• Subscription: the configuration record you create: a URL, a list of events to listen for, a status, and a signing secret.
• Endpoint / Destination URL: the HTTPS URL that receives the POST.
• Event: a typed thing that happened (e.g., contribution.approved). Each event has a name and a JSON payload.
• Wildcard: the special event selection * meaning “everything, including future events.”
• Payload: the JSON body of the webhook: includes the event type, an event ID, a timestamp, and the data for the resource.
• Signing secret: a random string unique to each subscription used to sign every outbound webhook.
• HMAC-SHA256: the cryptographic algorithm used to sign payloads.
• Signature header: x-overflow-webhook-signature-hmacsha256, the hex signature attached to each request.
• Secret roll / rotation: replacing the active signing secret with a new one, optionally with a grace window for dual-signing.
• Grace window: the period after a roll during which both the previous and new secrets sign each request.
• Delivery: a single HTTP attempt to a single subscription for a single event.
• Delivery log: the audit record of every delivery: request, response, status, timing, and attempt number.
• Resend: manually re-firing a previously-failed delivery from the dashboard.
• Retry: automatic re-attempt of a failed delivery by the queue worker on a backoff schedule.
• Backoff: progressively longer wait between retry attempts (over a 3-day window).
• Test event: a hand-crafted sample payload sent on demand from the dashboard so you can confirm an endpoint is wired up. Not logged, not retried.
• Enabled / Disabled: subscription status. Disabled subscriptions receive nothing and log nothing.
• Degradation episode: an open failing state for a subscription that starts when automated deliveries begin to fail and ends when Overflow disables the subscription (or the endpoint recovers). Drives the reminder email cadence.
• Failing email / inactive email: the two health notifications sent to the subscription creator. The failing email fires on reminder stages while the subscription is still enabled; the inactive email fires once Overflow auto-disables the subscription.
• Terminal failure: a delivery that will not be retried further — either a non-retriable HTTP response or a retriable failure that has exhausted the retry budget. Terminal failures trigger auto-disable and the inactive email.