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

# Receive real-time events with RentFAX webhooks

> Configure a webhook URL to receive JSON payloads when reports are submitted, disputes are filed, or identity checks complete in your RentFAX organization.

Webhooks let RentFAX notify your system the moment something meaningful happens — a report is submitted, a dispute is filed, or an identity check completes. Instead of polling the API for updates, you register a URL and RentFAX sends an HTTP POST with a JSON payload to that URL each time a matching event occurs.

Webhook delivery is configured per organization. You provide one URL and RentFAX routes all events for your org to it.

## How webhooks work

When an event is triggered in RentFAX, the platform reads the webhook URL stored in your organization's settings and sends a `POST` request to it with a `Content-Type: application/json` header. The request body contains the full event payload as JSON.

If the request fails — for example, because your server is temporarily unreachable — the failure is logged. Plan to handle retries on your end or design your endpoint to be idempotent.

## Set up your webhook

<Steps>
  <Step title="Build a receiving endpoint">
    Create an HTTPS endpoint on your server that accepts `POST` requests with a JSON body. Your endpoint must return a `2xx` status code to acknowledge receipt.

    ```typescript theme={null}
    // Example: Express.js receiver
    app.post("/webhooks/rentfax", express.json(), (req, res) => {
      const event = req.body;
      console.log("Received RentFAX event:", event.type);
      // Handle the event...
      res.sendStatus(200);
    });
    ```
  </Step>

  <Step title="Register your URL in dashboard settings">
    In the RentFAX dashboard, go to **Settings** and find the **Webhooks** section. Paste your endpoint URL into the **Webhook URL** field and save. RentFAX stores this URL against your organization and uses it for all subsequent event delivery.
  </Step>

  <Step title="Test delivery">
    Trigger a test event by submitting a report or filing a dispute in the dashboard. Check your server logs to confirm the payload arrived. You can also inspect the raw POST body to verify the structure matches your expectations.
  </Step>
</Steps>

<Warning>
  Your webhook endpoint is publicly reachable. Anyone who knows the URL can POST data to it. Validate that incoming requests originate from RentFAX by checking for expected fields in the payload (such as `orgId` matching your organization). Do not act on payloads that are missing required fields or have unexpected shapes.
</Warning>

## Payload structure

Every webhook RentFAX sends is a JSON object POSTed to your configured URL. The payload structure varies by event type, but all payloads share a common envelope.

```json theme={null}
{
  "type": "report.submitted",
  "orgId": "org_abc123",
  "timestamp": "2025-10-14T09:32:00Z",
  "data": {
    ...
  }
}
```

| Field       | Type   | Description                                        |
| ----------- | ------ | -------------------------------------------------- |
| `type`      | string | The event type that triggered this webhook.        |
| `orgId`     | string | The RentFAX organization ID the event belongs to.  |
| `timestamp` | string | ISO 8601 timestamp of when the event occurred.     |
| `data`      | object | Event-specific payload. See each event type below. |

## Event types

RentFAX sends webhooks for the following events.

### `report.submitted`

Fired when a new rental report is submitted for a renter in your organization.

```json theme={null}
{
  "type": "report.submitted",
  "orgId": "org_abc123",
  "timestamp": "2025-10-14T09:32:00Z",
  "data": {
    "reportId": "rpt_7f9e2d",
    "renterId": "rntr_4c8a1b",
    "renterEmail": "jane.doe@example.com",
    "riskScore": 720,
    "submittedBy": "user_9b3f22"
  }
}
```

### `dispute.filed`

Fired when a renter files a dispute against a record in their profile.

```json theme={null}
{
  "type": "dispute.filed",
  "orgId": "org_abc123",
  "timestamp": "2025-10-15T14:05:30Z",
  "data": {
    "disputeId": "dsp_3e7c90",
    "renterId": "rntr_4c8a1b",
    "renterEmail": "jane.doe@example.com",
    "recordType": "incident",
    "recordId": "inc_2d5b78",
    "reason": "Inaccurate charge"
  }
}
```

### `identity.check`

Fired when an identity check completes for a renter — for example, after a fraud detection scan or an insurance verification runs.

```json theme={null}
{
  "type": "identity.check",
  "orgId": "org_abc123",
  "timestamp": "2025-10-16T11:22:45Z",
  "data": {
    "checkId": "chk_1a4d56",
    "renterId": "rntr_4c8a1b",
    "renterEmail": "jane.doe@example.com",
    "result": "verified",
    "signals": ["duplicate_id_flag"]
  }
}
```

## Handling delivery failures

RentFAX logs a failure when your endpoint returns a non-`2xx` status or does not respond. The platform may retry delivery — design your endpoint to handle duplicate events safely by treating each event as idempotent (for example, by tracking processed `data.reportId` or `data.disputeId` values).

<Note>
  If your endpoint is down for an extended period, contact [support](https://app.rentfax.io/contact) to review any missed events for your organization.
</Note>

## Changing or removing your webhook URL

To update your webhook URL, go to **Settings** in the dashboard, edit the **Webhook URL** field, and save. RentFAX begins using the new URL immediately. To stop receiving webhooks, clear the field and save.

## Related

* [REST API overview](/api-reference/introduction)
* [API authentication](/api-reference/authentication)
* [Webhook events reference](/api-reference/webhooks/events)