Webhooks

​

Event categories

​

Where you configure events

1. Webhooks page - the outbound endpoint: URL, signing secrets, delivery health, and recent volume. Create the webhook here before you try to route any events to it.
2. Connector profile - which events fire from this connector in this project, and which webhook(s) each event is routed to. For programmatic events, toggling here provisions (or unprovisions) the underlying subscription with the connector for every linked account on the profile. Manual events are tagged Requires Setup and only fire once StackOne’s webhook URL is registered in the connector’s app config. See Scoping Connectors.

​

Quickstart

​

Verifying webhook signatures

import { createHmac, timingSafeEqual } from 'crypto';

function isSignatureValid(signature, rawBody, signingSecret) {
  if (!signature) return false;
  const expected = createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('base64url');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

• Hash the raw request bytes, not a re-serialized JSON string - JSON.stringify doesn’t guarantee byte-for-byte equality with what we sent.
• Compare in constant time with timingSafeEqual, not ===, so an attacker can’t infer the signature byte-by-byte from response latency.

​

Rotating signing secrets

1. On the Signing secrets tab, click Generate on the Generate new signing secret row, then Confirm. The new secret starts inactive - deliveries continue to use the active secret.
   
2. Copy the new secret from the Generate Signing Secret dialog, or later with the copy button on its row.
3. In your endpoint, accept signatures matching either the current secret or the new one.
4. Back in StackOne, open the … menu on the new secret’s row, click Activate (rotate), then Confirm. Deliveries now sign with the new secret, and the old secret switches to inactive.
   
5. Once you’ve confirmed everything’s still verifying, open the … menu on the old secret’s row and click Delete. Until you delete it, Activate (rotate) on the old secret switches back. You can’t retrieve or reactivate a deleted secret.
6. Remove the old secret from your verification code.

​

Managing a webhook

• Disable - stops delivery to your URL. Subscriptions with the connector stay active, so events keep flowing into StackOne and resume on enable.
• Enable - resumes delivery using the existing subscriptions.
• Delete - removes the webhook and cleans up the programmatic subscriptions with the connector for events that no other webhook is using.

​

Troubleshooting

• Events aren’t arriving. Check that the event is enabled on the connector profile and subscribed by the webhook. Both are required.
• Signature mismatches. Verify against the raw body, not a re-serialized JSON string. Confirm you’re using the currently-active secret.
• Data Sync events aren’t arriving. A Linked Account’s first run sends no events, because it sets the baseline. deleted events only come from a full re-sync. See When events are sent.
• Some accounts deliver, others don’t. Open the connector profile and confirm the linked account is active.
• 5xx loops. Your endpoint is returning an error and StackOne is retrying. Check your application logs and the webhook’s Last Triggered and 7-Day-Volume columns on the Webhooks page.
• Behind a firewall. Allow inbound traffic from StackOne’s outbound IP addresses.