Webhook Setup and Delivery Logs

Webhooks let you push real-time event notifications from ArkanPM to any system that speaks HTTP. This article walks through registration, event subscriptions, authentication, retry policy, and how to read delivery logs.

The webhook registry

Open Settings → Integrations → Webhooks. The registry lists every webhook endpoint configured for the tenant. Each entry shows:

• Name and description
• Target URL
• Event subscriptions
• Status (active, paused, failing)
• Last delivery timestamp and result

Registering a new webhook

Click Add webhook and fill in:

1. Name — a human-readable label.
2. Target URL — the HTTPS endpoint to deliver to.
3. Event subscriptions — select from the event catalog (work order created, work order completed, lease expiring, visitor checked in, inspection overdue, and many more).
4. Authentication secret — a shared secret used to sign each delivery. ArkanPM hashes payloads with this secret and includes an X-Signature header the receiver validates.
5. Custom headers — optional headers added to every delivery (for example, X-Tenant-Id or an authorization bearer).
6. Retry count — how many times to retry a failed delivery.
7. Timeout — how long to wait for a response before considering the delivery failed.

Save. The webhook is active immediately.

Event subscriptions

Events are grouped by module. A few examples:

• Maintenance — work order created, assigned, status changed, completed, SLA breached.
• Leasing — lease drafted, activated, renewed, terminated, expiring.
• Residents — service request submitted, visitor pass issued, booking confirmed.
• Inspections — inspection scheduled, overdue, submitted, approved.
• Warranty — warranty claim submitted, approved, resolved.
• Documents — document uploaded, access logged.

Subscribe to only the events your downstream system needs. Unused events waste delivery slots and increase noise.

Authentication

Each delivery includes an X-Signature header with the HMAC-SHA256 of the request body using the webhook secret. The receiving system recomputes the signature and compares. Reject any delivery where the signature does not match.

Custom headers let you add API keys, tenant identifiers, or tracing IDs for downstream systems.

Delivery guarantees

Every delivery tracks:

• HTTP status returned.
• Response body (truncated to a safe size).
• Attempt count.
• Next retry timestamp (if a retry is pending).

If the target returns a non-2xx status or times out, ArkanPM retries with exponential backoff up to the configured retry count. After exhaustion, the delivery is marked failed and a notification is sent to the integration owner.

Reading the delivery log

From a webhook's detail page, open Deliveries. Each row shows:

• Event type and event ID.
• Timestamp.
• Status (success, failed, retrying).
• HTTP status code.
• Duration in milliseconds.

Click a row to expand the full request and response. Integration logs also track success, error, and warning entries with error messages and durations — useful for triaging recurring failures.

Testing webhooks

Click Send test event from the webhook's detail page. ArkanPM sends a synthetic event with a known payload to the target URL. Use this during development and whenever you change the receiving endpoint.

Common pitfalls

• HTTP targets. Always use HTTPS. HTTP targets are rejected on creation.
• Aggressive timeouts. If your target regularly takes longer than the configured timeout, increase it rather than failing deliveries.
• Unbounded retries. Set retry count to a reasonable value. Infinite retries can pile up during outages.
• Missing signature validation. If you do not verify the X-Signature header, anyone with the URL can forge events.

What next

Read Arkan Handover and ERP integrations to see purpose-built integrations beyond webhooks.