> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ownright.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Enable real time updates in your system by using our webhooks

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 activity on the Ownright platform as it evolves 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:

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

## 🎯 Why we use webhooks

Real estate transactions move fast. Webhooks help you:

<ul>
  <li>Stay informed the moment something progresses</li>
  <li>Automatically update client records or timelines</li>
  <li>Reduce polling overhead and keep your app performant</li>
</ul>

## 📬 Webhook subscriptions

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

Each subscription includes:

<ul>
  <li>A callback URL: The endpoint Ownright will send events to</li>
  <li>A list of event types the URL should receive</li>
  <li>A webhook secret used to verify authenticity</li>
</ul>

### Registering a webhook subscription

Webhook subscriptions are registered via the API. Refer to your API's reference section for the specific mutations available.

When creating a subscription, Ownright will:

<ol>
  <li>Generate a verification token</li>
  <li>Send an HTTP POST request to your callback URL with the token</li>
  <li>Expect a response with the same token in the body</li>
</ol>

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

#### Verification example

**Request sent by Ownright:**

```http theme={null}
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:**

```http theme={null}
{
  "verification_token": "abc123"
}
```

## 📦 Receiving webhook events

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

| Header                         | HTTP Status                                               |
| ------------------------------ | --------------------------------------------------------- |
| `X-Ownright-Webhook-Signature` | HMAC SHA256 signature of the request                      |
| `X-Ownright-Webhook-Timestamp` | Timestamp of the request (used to prevent replay attacks) |

### Verifying the webhook

To confirm that a webhook request is legitimate:

<ol>
  <li>
    Concatenate: `"{timestamp}.{raw_request_body}"`
  </li>

  <li>Hash it using `HMAC SHA256` with your webhook secret</li>
  <li>Compare the result to the value in `X-Ownright-Webhook-Signature`</li>
</ol>

If they match, the event is authentic.

<Note>
  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.
</Note>

## 🗂 Supported events

The specific events available depend on which API you are using. Refer to the **Webhooks** section in your API's reference for the full list of supported events and their schemas.

## 💡 Best practices

<ul>
  <li>
    Respond with a 2xx status code within 5 seconds to acknowledge receipt
  </li>

  <li>
    Retry logic is built in — failed deliveries will be retried with exponential
    backoff
  </li>

  <li>Your webhook URL should be HTTPS and publicly accessible</li>
  <li>Always verify webhook signatures for security</li>
</ul>