Webhooks guide

Webhooks deliver near real-time updates whenever finance data changes. Use them to keep internal dashboards in sync, trigger downstream automations, or avoid polling the API for status updates.

Typical workflow

1. Register a webhook - Define the event type you care about and the target URL that should receive notifications.
2. Store the shared secret - Creation responses include a secret. Save it securely; you will need it to verify payloads.
3. Handle events - Expose an HTTPS endpoint that accepts POST requests, validates the signature header, and queues work for processing.
4. Monitor delivery - Log attempts and respond quickly with 2xx status codes. Krebit Finance retries on transient failures and may disable webhooks that repeatedly return errors.

Event catalog

Event values are defined in the API reference for your tenant. Use the values listed under Webhooks -> WebhookStoreRequest when creating a subscription. If you need new events, contact Krebit support.

Common events include:

Event	Value	When it fires
Act created	act.created	A new act is created and available for downstream processing.

Verify signatures

Webhook requests include an HMAC signature header (X-Signature) and the client identifier in X-Client-Id. The secret returned during creation is used to compute this hash.

import crypto from 'node:crypto';

function verifySignature(rawBody: Buffer, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Make sure your HTTP framework provides access to the raw request body. Parsing JSON before computing the signature may change whitespace and break validation.

Reliability best practices

• Respond quickly - Acknowledge requests with 200 as soon as you enqueue work. Process the event asynchronously to avoid timeouts.
• Handle retries - Design idempotent consumers. Store the id field included in each payload and ignore duplicates.
• Secure endpoints - Require HTTPS, restrict IP ranges if possible, and rotate webhook secrets on a schedule.
• Test first - Use tunneling tools against your tenant with test data to validate your handler before going live.

Troubleshooting

• No payloads arriving - Confirm your endpoint is reachable from the public internet and returns 2xx responses.
• Signature mismatch - Verify you are using the latest secret and the unmodified raw body when calculating the HMAC.
• Too many retries - Log attempts and error messages. Krebit Finance may disable the webhook after repeated failures; re-enable it once your handler recovers.

When you need the exact payload structure or request fields, open the Webhooks section in the generated API reference from the sidebar.