Webhook setup and events

How webhooks work

Instead of polling the API for changes, you register an HTTPS endpoint and Arvexi sends an HTTP POST request to it whenever a subscribed event occurs. Each request contains a JSON payload with the event type, a timestamp, and the full resource that changed.

Webhooks are push-based and near-real-time. Most events are delivered within two seconds of the underlying change. This makes webhooks ideal for keeping external systems in sync such as ERPs, data warehouses, Slack channels, or custom dashboards.

Event types

Arvexi groups events by resource. You can subscribe to individual event types or entire resource groups:

• lease.created : A new lease record was added.
• lease.updated : A lease record was modified (e.g., remeasurement, amendment, or field edit).
• lease.terminated : A lease was fully terminated or expired.
• journal_entry.posted : A journal entry was posted and is ready for export.
• reconciliation.completed : An account reconciliation was marked as complete.
• document.extracted : Arvexi Cortex finished extracting data from an uploaded document.
• close.period_closed : A period was officially closed by an approver.
• close.task_completed : A close task was marked as done.
• user.invited : A new user was invited to the organization.
• user.deactivated : A user was deactivated by an admin.

More event types are added regularly. The full list is always available in Settings → API → Webhooks → Event catalog.

Configuring an endpoint

Navigate to Settings → API → Webhooks and click Add endpoint. Provide:

1. URL: The HTTPS endpoint that will receive POST requests. HTTP (non-TLS) endpoints are not supported.
2. Events: Select the event types you want to subscribe to. You can update this list at any time without generating a new endpoint.
3. Description: An optional label for your team (e.g., “Production ERP sync” or “Slack notifications”).

After saving, Arvexi generates a signing secret for the endpoint. Copy it immediately; it is shown only once. You will use this secret to verify incoming payloads.

HMAC signature verification

Every webhook request includes an X-Arvexi-Signature header containing an HMAC-SHA256 signature of the raw request body. Always verify this signature before processing the payload to confirm it originated from Arvexi and was not tampered with in transit.

Verification steps:

1. Read the raw request body as a UTF-8 string. Do not parse JSON first. The signature covers the exact bytes sent.
2. Compute an HMAC-SHA256 digest of the raw body using your endpoint’s signing secret as the key.
3. Compare the computed digest with the value in X-Arvexi-Signature using a constant-time comparison function to prevent timing attacks.

Example in Node.js:

import crypto from "crypto";

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

Reject any request where the signature does not match. Return a 401 Unauthorized status so Arvexi marks the delivery as failed and retries it.

Idempotency keys

Every webhook payload includes an idempotency_key field, a unique identifier for that specific delivery. Arvexi guarantees that the same idempotency key will not be reused for a different event within a 24-hour window.

Use this key to deduplicate deliveries on your end. If your endpoint receives a payload with an idempotency key it has already processed, return a 200 OK without re-processing. This is important because retries (see below) can result in the same event being delivered more than once.

Store processed idempotency keys in a fast lookup store (Redis, database table, or in-memory cache) with a 24-hour TTL to match Arvexi’s deduplication window.

Retry behavior

If your endpoint returns a non-2xx status code or does not respond within 15 seconds, Arvexi retries the delivery using an exponential backoff schedule:

• Attempt 1: Immediate.
• Attempt 2: After 30 seconds.
• Attempt 3: After 5 minutes.
• Attempt 4: After 30 minutes.
• Attempt 5: After 2 hours.
• Attempt 6: After 8 hours.

After six failed attempts, the delivery is marked as failed and no further retries are attempted. Failed deliveries appear in the webhook logs in Settings → API → Webhooks → Deliveries, where you can inspect the payload and manually retry.

If an endpoint accumulates 50 consecutive failures, Arvexi automatically disables it and sends an email notification to all organization admins. Re-enable the endpoint in Settings once you have resolved the issue.

Testing webhooks

Arvexi provides two tools for testing your webhook integration before going live:

• Test event: In the endpoint configuration panel, click Send test event. Arvexi sends a synthetic event with test: true in the payload. Use this to verify your endpoint is reachable and your signature verification logic works.
• Delivery log: Every delivery is logged with the full request payload, response status code, response body (first 1 KB), and latency. Use the log to debug failures without adding logging to your own infrastructure.

For local development, use a tunneling service like ngrok or Cloudflare Tunnel to expose your local server to the internet. Set the tunnel URL as your webhook endpoint during development, then switch to your production URL when you deploy.

For more on how Arvexi handles duplicate deliveries and request throttling, see the rate limiting and idempotency article.