Webhooks

We can configure our API to send REST messages to your service whenever we scan a document for one of your customers.

Setting up Webhooks

Contact support@hoxtonmix.com to get set up - you just need to send us your receiving Webhook URL. Note that you will need to provide an endpoint URL, a username and optionally a password. We will send the username and password (or a blank string) in the Authorization header of the request.

Webhook Specification

info

The ai_metadata object will only be populated with data if our Partner arrangement includes it. If not, the fields will be empty.

Every time we receive and scan a piece of mail for one of your customers we will send a message to your Webhook URL with the following JSON payload:

{
    "id": "our unique postal item id",
    "external_id": "your external customer id sent on account creation",
    "url": "the url to download the postal contents image (pdf format)",
    "url_envelope_front": "the url to download the envelope front image (jpeg format)",
    "url_envelope_back": "the url to download the envelope back image (jpeg format)",
    "file_name": "our filename"
    "ai_metadata": {
        "sender_name": "detected sender organization or individual",
        "document_title": "title of the document",
        "reference_number": "the main reference number found in the document",
        "summary": "a brief summary of the document contents",
        "industry": "detected industry classification",
        "categories": ["primary category", "secondary category"],
        "sub_categories": ["relevant sub_category 1", "relevant sub_category 2"],
        "key_information": ["important point 1", "important point 2"]
    }
}

A real-life example might look like this:

{
    "id": "1296480",
    "external_id": "2346803124592",
    "url": "https://s3.hoxtonmix.com/29iheg8ht80qy22tgiwh0wougher0.pdf",
    "url_envelope_front": "https://s3.hoxtonmix.com/oaeg20ha34pghowegowiehg0.jpg",
    "url_envelope_back": "https://s3.hoxtonmix.com/weg203tajaerahgshrauhgr.jpg",
    "file_name": "the_a_team_limited_1296480.pdf"
    "ai_metadata": {
        "sender_name": "Trotters Independent Traders",
        "document_title": "Statement of Account",
        "reference_number": "Statement-679229",
        "summary": "Monthly service statement for April 2025",
        "industry": "Professional Services",
        "categories": ["Financial", "Official / Legal"],
        "sub_categories": ["Regulatory-Communication", "Legal-Notice"],
        "key_information": [{"key": "Our Reference", "value": "679229"}, {"key": "Date of Issue", "value": "2025-03-08"}, {"key": "Invoice Date", "value": "03/02/2025"}, {"key": "Invoice Number", "value": "1856551"}, {"key": "Total Amount", "value": "£180.00"}, {"key": "Contact Email", "value": "delboy@trotters.traders"}, {"key": "Contact Phone", "value": "+44 (0) 217 666 6666"}]
    }
}

You will need to download the image from the url fields upon receipt of the webhook as the url will expire after 24 hours.