Enriching

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

ILSA will automatically order your enrichers such that each field is calculated before it is used by another enricher. In the Backoffice you can see the ordering ILSA has determined. Sometimes ILSA can’t automatically make the choice. We call that a conflict.

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

You can create and manage webhooks in the Backoffice. After creating a webhook it can be installed on one or more instances.

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 display an error to the advertiser you can use HTTP response code 422 with Content-Type: text/plain and return a short message to be relayed back to the advertiser. The vehicle will be rejected and removed from your ILSA instance.

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-Timestamp 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();
}

Conflicts

There are a few cases in which ILSA can’t automatically determine the ordering of internal and your enrichers. In those cases it will ask you to decide in the Backoffice. Here are some examples:

Sometimes it’s difficult to determine what the correct choice is. Especially if one of the enrichers is an internal enricher and you don’t know exactly what it does. Feel free to contact us for help with any conflicts.

On the Enrichers page you can see previous choices made (they are called forced orderings) and change them.

If you make a chance to enrichment (e.g. adding a new Webhook or TypeScript Enricher, or changing their input or output fields) you might create a conflict. The backoffice will indicate this clearly and ask you to solve it. Enrichment is paused while your instance is in conflicted state (because we don’t know in which order to execute the enrichers) which means vehicles on your site aren’t getting updated. We expect you to resolve this in a timely fashion. Otherwise we might need to revert your instance back to its old (working) configuration. Of course feel free to contact us if you need any help.