Manage webhook

  1. Dashboard
  2. Manage webhook
  3. Documentation

Receive Hemnet events in your webhook endpoint

Webhooks allow you to be notified when certain events happen in Hemnet.

Get started

Register an url where you want to receive the webhooks and subscribe to events under our webhooks settings page.

ON THIS PAGE

The Webhook

Headers

User-Agent "Hemnet API Client"

Content-Type "application/json"

X-Timestamp "1712918356462"

The timestamp when the request was made. Unix timestamp format (milliseconds since the Unix Epoch).

X-Signature "secret-signature"

The HMAC-SHA256 hex signature(s) to verify the authenticity of the request, generated with your active webhook key(s) and the json payload.

Attention: The X-Signature header can contain two signatures when keys are being rotated. In such cases, they are separated by a comma within the string. This allows for a smooth transition while changing keys. For example: "oldKeySignature,newKeySignature"

X-Request-Id "d2caad70-082f-4553-bbde-dbdca520361a"

A unique identifier for a particular request. Useful for tracking and debugging purposes. Allows easier tracing of requests through the systems.

Payload
{
  "type": string,
  "action": string,
  "data": object
}

Receiving & processing webhooks

Validating incoming requests

When receiving webhooks, it's important to validate the incoming requests. This can be done by checking the signature of the request, which is provided in the headers. The signature is generated using the payload of the request and a secret key that only you and Hemnet know. By generating the signature on your end and comparing it to the signature in the headers, you can verify the request is from Hemnet.

Pay special attention to the payload when constructing the signature! Since the content of certain webhooks may include user generated messages, it might contain special characters. For compatibility reasons, we encode these as html entities (\u0026 instead of & for example) in the webhook payload. It's normal for certain languages to decode these automatically. It's important that your implementation uses the raw body when constructing the signature key on your side.

You can also choose to validate the origin IP address of the webhook request. Hemnet uses these IP addresses:

Production (hemnet.se) IP addresses
  • 52.215.23.149
  • 52.48.66.139
  • 52.18.194.163
Sandbox (testhemnet.se) IP addresses
  • 34.252.42.223
  • 54.72.180.48
  • 34.249.104.221

We cannot guarantee that this list won't be extended in the future. We will announce any changes to the list of IP addresses in advance to the best of our abilities.

Process events asynchronously

Processing webhooks should be done asynchronously. When your endpoint receives a webhook, it should respond with a 200 OK status to the request as soon as possible to acknowledge receipt. The actual processing of the webhook data should be done in a separate process, so it doesn't block the response. This is important because we might consider the webhook delivery failed unless we receive a response within a certain amount of time.

Idempotency

It's a good practice to make your webhook processing idempotent. That means if you receive the same webhook multiple times, processing it more than once should not have different effects. This is important because webhooks can be delivered more than once in case of network issues or in the case that Hemnet didn't receive a successful response.

Retries

In the event that your endpoint does not return a 200 OK status code, our system will make new attempt to to deliver the webhook over a period of 7 days. These retries are not immediate; instead, they follow an exponential backoff schedule. This means that the time between each retry will progressively get longer to reduce the load on your server and increase the chances of a successful delivery. It's crucial to ensure your system is prepared to handle retries and can successfully acknowledge receipt of the webhook with a 200 OK status code to prevent unnecessary retries.

Stability guarantee

Our webhooks API is designed with stability in mind. We understand the importance of a reliable APIs and the impact changes can have on your applications. Therefore, we make the following guarantees:

  1. Deprecation Process: If an attribute or behavior needs to be changed or removed, we will mark it as deprecated and maintain it for a certain period of time. This gives you ample time to adapt your applications to the upcoming changes. After the deprecation period, the attribute or behavior may be removed.
  2. No Sudden Removal of Attributes: Once an attribute is added to an event payload, we guarantee it will not be removed without a deprecation notice. You can rely on all existing attributes to remain available and maintain their meaning until the end of their deprecation period.
  3. No Change in Data Types: The data type of an existing attribute will not change. If an attribute is initially provided as a string, it will always be a string. Enums may grow, but their member's data type remains consistent. This ensures that your data parsing and handling logic will not break.
  4. Backward Compatibility: Any changes to the API will be backward compatible. If we need to change an attribute or behavior, we will create a new attribute or event and maintain the old one until the end of its deprecation period.

By adhering to these principles, we aim to provide a stable, reliable API that you can confidently integrate with your applications.

Types of events

CONTACT CREATE

Occurs whenever a potential customer has expressed interest in a product or service. Typically indicated through some form of contact or engagement, such as submitting an inquiry or filling out a form.

Payload
{
  "type": "CONTACT",
  "action": "CREATE",
  "data": contact object
}

The Contact object

A contact is a message from a Hemnet user who has expressed interest in a contacting a broker or agency. This interest is typically indicated through some form of contact or engagement, such as submitting an inquiry or filling out a form.

Attributes

id string

This is a unique identifier for the Contact object.

recipientType enum

This field indicates who is the intended recipient type of the Contact. One of:

  • BROKER
  • BROKER_AGENCY

email nullable string

This is the email address of the Contact.

phone nullable string

This is the phone number of the Contact.

firstName nullable string

This is the first name of the Contact.

lastName nullable string

This is the last name of the Contact.

message nullable string

This is a free text message which may be supplied by the Contact.

listing nullable object

This is an object that contains information about the listing that the Contact relates to.

listing object

id integer

This is a unique identifier for the listing.

externalId nullable string

This is the unique, external identifier (originating from your broker system) for the listing, which can be null if the listing was originally created by another broker system and then migrated to yours.

broker nullable object

This is an object that contains information about the broker if the recipientType is BROKER.

broker object

id integer

This is a unique identifier for the broker.

email integer

This is the email address of the broker.

fullName string

This is the full name of the broker.

brokerAgency nullable object

This is an object that contains information about the broker agency.

brokerAgency object

id integer

This is a unique identifier for the broker agency.

externalId nullable integer

This is the unique, external identifier (originating from your broker system) for the brokerAgency, which can be null if the brokerAgency was originally created by another broker system and then migrated to yours.

contactPreference enum

This field indicates the preferred method of communication for the Contact. One of:

  • EMAIL
  • PHONE

contactReason nullable enum

This field indicates the reason why the Contact reached out. One of:

  • SELLING_ADVICE
  • BUYING_ADVICE
  • OTHER

streetName nullable string

This is the name of the street which the contact has stated as their home address.

streetNumber nullable string

This is the number of the street which the contact has stated as their home address.

postalCity nullable string

This is the postal city in which the location that the contact provided is located.

preapprovedMortgage nullable boolean

This is a boolean field that indicates whether the Contact has a pre-approved mortgage.

source enum

This field indicates from which page, view or source the Contact reached out from. One of:

  • BROKER_PROFILE_CONTACT_FORM
  • BROKER_AGENCY_PAGE_CONTACT_FORM
  • LISTING_UPCOMING_CONTACT_FORM
  • LISTING_FOR_SALE_CONTACT_FORM
  • LISTING_SOLD_CONTACT_FORM

A Contact object

{
  "id": "c7bc3070-fca2-4ccc-a705-c0b275fdf0a1",
  "recipientType": "BROKER",
  "email": "[email protected]",
  "phone": "070111222333",
  "firstName": "John",
  "lastName": "Doe",
  "message": "I am interested in this property",
  "listing": {
    "id": 12345678,
    "externalId": "abc123def",
  },
  "broker": {
    "id": 12345,
    "email": "[email protected]",
    "fullName": "Anon Ymous"
  },
  "brokerAgency": {
    "id": 654321,
    "externalId": 123
  },
  "contactPreference": "EMAIL",
  "contactReason": "OTHER",
  "streetName": "Test street",
  "streetNumber": "12A",
  "postalCity": "Testköping",
  "preapprovedMortgage": false,
  "source": "LISTING_FOR_SALE_CONTACT_FORM"
}