Webhooks Implementation Guide

Webhooks allow developers to subscribe to specific events and receive real-time notifications. This guide will walk you through the process of subscribing to events, managing subscriptions, and understanding the types of events available.

How to Subscribe to Events

To subscribe to an event, you need to send a POST request to the Repliers webhooks endpoint with the target URL and the event you want to subscribe to. Here's an example:

curl --request POST \
  --url https://api.repliers.io/webhooks \
  --header 'REPLIERS-API-KEY: {ACCOUNT-API_KEY}' \
  --header 'content-type: application/json' \
  --data '{"target_url":"https://yourdomain.com/unique-path","event":"listing.created"}'

Note: The target_url value must be unique.

Subscription Verification (Important)

Upon a successful subscription, an empty POST request is immediately sent to the target_url containing an X-Hook-Secret header with a random value. To complete the subscription, the subscriber must return a 200 response to this POST containing the same header key and value.

curl --request POST \
  --url {target_url} \
  --header 'X-Hook-Secret: {random-value}'

Authentication

All subsequent requests to the specified target will contain the same value for the x-api-key header. This value may be used to authenticate all subsequent requests.

Supported Events

Here is a list of currently supported events that developers can subscribe to:

agent.created
agent.updated
agent.deleted
client.created
client.updated
client.deleted
search.created
search.updated
search.deleted
search.match.created
search.match.updated
message.created
message.updated
message.deleted
listing.created
listing.updated
listing.deleted

Example Webhook Request

Here's an example of a webhook request sent to a target_url when a listing is deleted:

curl --request POST \
  --url {target_url} \
  --header 'X-Hook-Secret: {some-value}' \
  --header 'content-type: application/json' \
  --data '{
    "data": {
        "boardId": 49,
        "mlsNumber": "21000009"
    },
    "hook": {
        "id": 123,
        "event": "listing.deleted",
        "header": "x-api-key",
        "secret": "{some-value}",
        "target_url": "{target_url}"
    }
}'

Working With The Previous Object When Listings Are Updated (listing.updated)

When you've subscribed to the listing.updated event, you will receive a webhook request to the target_url specified in your subscription whenever a listing's information changes. The webhook payload contains two main components: the previous object and the data object.

The previous object provides the fields that have changed along with their previous values, allowing you to compare them to the new values. Here is an example of what the previous object may look like:

... },
    "previous": {
        "status": "A",
        "updatedOn": "2024-09-19T16:00:01.000Z",
        "lastStatus": "New"
    }...

In this example:

The status field previously held the value 'A'.
The lastStatus field previously held the value 'New'.
The updatedOn timestamp shows when the listing was last updated before the current change.

This means the listing's status and lastStatus have now been updated to new values, which are stored in the data object of the webhook request. You can access the new values in the data object like so:

{
  "data": {
    "status": "U",
    "updatedOn": "2024-09-21T12:30:45.000Z",
    "lastStatus": "Sld"
  }...
}

In this case, the new values for status and lastStatus are 'U' and 'Sld', respectively, reflecting the latest state of the listing.

By using the previous object, you can track changes in real time, making it easy to trigger actions based on specific field updates or maintain historical records of a listing’s status transitions.

Summary

By following the steps outlined above, you can easily subscribe to and manage webhook events to receive real-time updates and notifications for various actions within your application. If you have any questions or need further assistance, please contact our support team.

Updated on: 24/09/2024