Enriching

Enriching is one of the steps a listing goes through before being published. Besides many internal enrichers we have Webhook enrichers which can communicate with your server.

Webhooks

With Webhooks your server will receive a HTTP POST request from ILSA with vehicle information and you can return additional information to be attached to the vehicle.

Webhooks can be managed in the Backoffice. The main properties of a webhook are:

• The endpoint (which URL should we call?)
• Which fields you want to receive. These should include all the information your webhook needs, but nothing more. ILSA will cache your responses based on the hash of the input, so by including fields you don’t use the effectiveness of the cache is reduced.
• Fields you plan on returning (yoursite.final_term, yoursite.monthly_amount_24 and yoursite.monthly_amount_36 in the example below). You can choose your own names, but we do prefer you use a prefix indicating those fields are custom for you, to keep things clear. You can create more complex structures if needed. These fields will then be available in the backoffice for you to add as searchable fields (filters), use in ordering or add to fieldsets.
• The number of parallel requests ILSA is allowed to make. If set to 1 all calls will be made sequentially.
• A shared secret if you want the requests signed

Creating new webhooks in the backoffice is not yet supported. Contact us and we’ll configure it for you.

Example

Here’s an example request:

POST /ilsa-enricher HTTP/1.1
Host: www.yoursite.com
User-Agent: ILSA enricher v1.0 (info@ilsa.cloud)
Content-Type: application/json

{
    "sales_conditions": {
        "pricing": {
            "asking": {
                "business": {
                    "in_eur": {
                        "excl_vat": {
                            "amount": 24426
                        },
                        "incl_vat": {
                            "amount": 28450
                        }
                    }
                }
            }
        },
        "margin_scheme": "vat"
    }
}

and an example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "yoursite": {
  	    "final_term": 3500
        "monthly_amount_24": 399,
        "monthly_amount_36": 299
    }
}

Error handling

Any errors from your webhook are automatically retried a few minutes later. You can view the latest reported errors in the Backoffice.

If you want to reject a vehicle use HTTP response code 422 with a short message to be relayed back to the advertiser.

HTTP/1.1 422 Unprocessable Content
Content-Type: text/plain

The vehicle could not be found in the manufacturer database.

Testing

If you want to test changes you’re making to your webhook implementation, you can go to the Settings page of the webhook and click the Test button to send test requests.
You can change the URL to point to your development environment to send tests requests there. As long as you don’t click Save you won’t affect your instance.

Caching

As mentioned above, we cache enrichers based on their inputs. Your webhook should give the same result when given the same input.

Purge cache

Sometimes the world changes however. Maybe you’ve changed your interest rate and all vehicles need to be enriched again. In the Backoffice you can manually purge an enricher. This can also be done for a specific advertiser or object.
Purging the cache will make ILSA send all vehicles through enrichment again.

You can also automate purging using the Hexon API, for example:

POST https://api.hexon.nl/ilsa/api/v1/rest/webhooks/mywebhook/purge
Content-Type: application/json
Authorization: Basic [base64(<username>:<password>)]

{
	"object_id": 12345
}

Expiration

Your webhook can return the HTTP response header X-ILSA-Expiry-Time to tell ILSA to automatically purge the cache at a certain time. The value is a Unix timestamp (in seconds).

Signatures

Optionally, a shared secret can be entered which ILSA will use to sign the requests. This allows you to confirm the request is originating from the ILSA servers and the payload has not been tampered with. ILSA uses HMAC SHA256 and adds the signature in the header X-Signature-SHA256.

import (
	"crypto/hmac"
	"encoding/base64"
)

const ilsaSharedSecret = "secret-to-be-configured"

func VerifiedBody(r *http.Request) ([]byte, error) {
	expected, err := base64.StdEncoding.DecodeString(r.Header.Get("X-Signature-SHA256"))
	if err != nil {
		return nil, errors.New("bad signature")
	}
	body, err := io.ReadAll(r.Body)
	if err != nil {
		return nil, err
	}
	mac := hmac.New(sha256.New, []byte(ilsaSharedSecret))
	mac.Write(body)
	if !hmac.Equal(expected, mac.Sum(nil)) {
		return nil, errors.New("bad signature")
	}
	return body, nil
}

$body = file_get_contents('php://input');
if(!hash_equals(hash_hmac('sha256', $body, 'secret-to-be-configured'), $_SERVER['HTTP_X_SIGNATURE_SHA256'])) {
	http_response_code(403);
	exit();
}