Webhooks allow Ownright to proactively notify your system when important events happen — without requiring you to constantly poll the API. They’re the best way to keep your platform in sync with referrals and matters as they evolve in real time.

​
🔔 What are webhooks?

A webhook is a lightweight HTTP request sent from Ownright to your server when a specific event occurs. For example, when a referral is converted into a matter, you’ll receive a webhook event immediately — no need to poll for updates.

Webhooks enable:

  • Real-time updates to your internal systems
  • Triggering business logic or workflows (e.g. status sync, UI changes)
  • Scalable and event-driven integrations

​
🎯 Why we use webhooks

Real estate transactions move fast. Webhooks help you:

  • Stay informed the moment a matter progresses
  • Automatically update client records or timelines
  • Reduce polling overhead and keep your app performant

​
📬 Webhook subscriptions

To get started with webhooks you will need to create a “webhook subscription”. Webhook subcriptions allow you to register your server to receive specific events.

Each subscription includes:

  • A callback URL: The endpoint Ownright will send events to
  • A list of event types the URL should receive

  • A webhook secret (configured in your Partner Dashboard) to verify authenticity

​
Registering a webhook subscription

Webhook subscriptions are registered via the API. In the future, this will be available through the Partner Dashboard.

When creating a subscription, Ownright will:

  1. Generate a verification token
  2. Send an HTTP POST request to your callback URL with the token
  3. Expect a response with the same token in the body

If verification succeeds, the webhook subscription will be created and your callback URL will begin to receive events.

​
Verification example

Request sent by Ownright:

POST /your/callback/url HTTP/1.1
Content-Type: application/json
X-Ownright-Webhook-Signature: signature
X-Ownright-Webhook-Timestamp: timestamp

{
  "verification_token": "abc123"
}

Expected response from your server:

{
  "verification_token": "abc123"
}

​
📦 Receiving webhook events

When an event occurs, we send an HTTP POST request to your callback URL with a JSON payload.

HeaderHTTP Status
X-Ownright-Webhook-SignatureHMAC SHA256 signature of the request
X-Ownright-Webhook-TimestampTimestamp of the request (used to prevent replay attacks)

​
Verifying the webhook

To confirm that a webhook request is legitimate:

  1. Concatenate: "{timestamp}.{raw_request_body}"

  2. Hash it using HMAC SHA256 with your webhook secret
  3. Compare the result to the value in X-Ownright-Webhook-Signature

If they match, the event is authentic.

Tip: You can also use the timestamp to reject requests that are too old (e.g., more than 5 minutes) to guard against replay attacks.

​
🗂 Supported events

Some of the key webhook events you can subscribe to include:

  • referral.state_changed – A referral’s lifecycle stage has changed (i.e. converted to matter)

  • matter.state_changed – A matter’s lifecycle stage has changed (i.e. closing completed)

You can find the full list of supported events and their schemas in the Webhook reference.

​
💡 Best practices

  • Respond with a 2xx status code within 5 seconds to acknowledge receipt

  • Retry logic is built in — failed deliveries will be retried with exponential backoff

  • Your webhook URL should be HTTPS and publicly accessible
  • Always verify webhook signatures for security