Skip to main content

Webhooks

We can configure our API to send REST messages to your service whenever something happens on one of your customers' accounts - for example when we scan a document, when a message arrives on one of their WhatsApp For Business numbers, or when a person's KYC status changes.

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.

The Authorization header is the only authentication scheme we support.

You have a single Webhook URL and a single set of credentials for your account. Every event is delivered to that URL, and every payload contains an event field telling you what happened so that you can route it within your own systems.

Source IP Addresses​

Our webhook calls are sent from AWS eu-west-2 (London) using dynamically assigned addresses. We cannot provide a fixed IP address or range that is stable enough to allowlist, so please authenticate our requests using the Authorization header rather than by source IP.

Retries and Failed Deliveries​

If your endpoint does not return a 2xx response we will retry the delivery twice, about 15 seconds apart, so three attempts in all. After the final attempt the webhook is moved into a failed state and we notify your nominated point of contact.

You can re-trigger a failed webhook yourself from the Partner Portal.

info

Re-triggering a webhook rebuilds its payload before it is sent, so the url, url_envelope_front and url_envelope_back links are freshly signed and valid for 24 hours from the re-trigger. The payload reflects the mail item's current state, so it can differ from the original delivery - for example, a rescanned item delivers the new scan's url and file_name. A re-trigger returns a 400 error if the mail item no longer has a content scan.

Recovering Expired Downloads​

If you need to recover a mail item whose links have expired, you have two options:

  • Call the List Mail Items endpoint. It generates fresh download URLs on every request, which makes it the simplest way to reconcile mail items you failed to process.
  • Use Resend mail items in the Partner Portal. This generates a brand new webhook with fresh download URLs. Where you have webhooks enabled, this only triggers the webhook - it does not email your customer.

Events​

EventSent when
mail.scannedWe receive and scan a piece of mail for one of your customers.
sms.receivedA message arrives on one of your customers' WhatsApp For Business numbers.
kyc.updatedThe KYC status of a person on one of your customers' subscriptions changes.

Mail scanned (mail.scanned)​

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:

{
"event": "mail.scanned",
"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:

{
"event": "mail.scanned",
"id": "1296480",
"external_id": "2346803124592",
"url": "https://hoxtonmix-scans-production.s3.amazonaws.com/29iheg8ht80qy22tgiwh0wougher0.pdf",
"url_envelope_front": "https://hoxtonmix-scans-production.s3.amazonaws.com/oaeg20ha34pghowegowiehg0.jpg",
"url_envelope_back": "https://hoxtonmix-scans-production.s3.amazonaws.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.

Scan Download Hosts​

The url, url_envelope_front and url_envelope_back fields always point at one of the following hosts, depending on the environment that sent the webhook. Add both to your firewall or proxy allowlist if you restrict outbound traffic.

EnvironmentHost
Productionhttps://hoxtonmix-scans-production.s3.amazonaws.com
Staginghttps://hoxtonmix-scans-staging.s3.amazonaws.com

Allowlist the host only - the path and query string of each URL are generated per scan and change every time, and the URL itself expires after 24 hours.

WhatsApp For Business SMS received (sms.received)​

Sent when a message arrives on a WhatsApp For Business number that you provisioned for one of your customers through the /whatsapp-number endpoint.

When you have a Webhook URL configured, this message replaces the forwarding email for those numbers - we send you the webhook instead of emailing the number's forwarding_email_address. If you do not have a Webhook URL configured, the forwarding email is sent as usual.

The payload looks like this:

{
"event": "sms.received",
"message_id": "the unique id of the received message",
"external_id": "your external customer id sent on account creation",
"phone_number": "the WhatsApp For Business number that received the message",
"nickname": "the nickname assigned to that number",
"from_number": "the number that sent the message",
"message_body": "the text of the message",
"received_at": "the time we received the message"
}

A real-life example might look like this:

{
"event": "sms.received",
"message_id": "SM8f2a1c4b9d6e47f0a3b5c7d8e9f01234",
"external_id": "9XJJ02eZvKYlo2ClwuJ",
"phone_number": "+447700900123",
"nickname": "Derek Trotter",
"from_number": "+447700900456",
"message_body": "Can you send the invoice over again please?",
"received_at": "2026-09-15T10:23:04+00:00"
}

message_id is unique to the received message and is stable across retries, so you can use it to de-duplicate messages on your side.

external_id is the external ID of the customer the number belongs to - the same one you supplied when creating the number, which may also be the external ID of that customer's Virtual Office subscription.

KYC updated (kyc.updated)​

Sent when the KYC status of a person on one of your customers' subscriptions changes, so that you do not need to poll for it. This webhook is only sent if your customers complete KYC with us themselves. If you carry out KYC on your customers' behalf, you will not receive it.

It is off by default - contact support@hoxtonmix.com to have it turned on for your account.

We send it every time a person's ID verification or proof of address changes status - for example when they start or submit a verification, when it is approved or declined, or when a new verification link is issued and the status goes back to NOT_STARTED. We also send it when the result of the person's AML check changes kyc_checks_passed. The AML result itself is not included in the payload, so an AML change that leaves kyc_checks_passed as it was does not send a webhook.

If a status has not changed, we do not send a webhook. You may still receive two payloads that differ only by updated_at, as some status changes are not visible to you; see SUBMITTED below.

The payload looks like this:

{
"event": "kyc.updated",
"subscription_id": "our unique subscription id",
"external_id": "your external customer id sent on account creation",
"person": {
"id": "our unique id for this person, stable across webhooks",
"first_name": "the person's first name",
"middle_name": "the person's middle name",
"last_name": "the person's last name",
"phone_number": "the person's phone number",
"email_address": "the person's email address",
"date_of_birth": "the person's date of birth (YYYY-MM-DD)",
"url": "the link the person uses to complete verification",
"kyc_checks_passed": "true once the person's ID, proof of address and AML checks have all passed",
"id_verification": {
"status": "the status of the person's ID verification",
"reason": "why it was declined or needs resubmitting, otherwise null"
},
"address_verification": {
"status": "the status of the person's proof of address",
"reason": "why it was declined or needs resubmitting, otherwise null"
}
},
"kyc_checks_completed": "true once every person on the subscription has passed KYC",
"updated_at": "the time the status changed"
}

A real-life example, sent when a person's proof of address is declined, might look like this:

{
"event": "kyc.updated",
"subscription_id": 48213,
"external_id": "9XJJ02eZvKYlo2ClwuJ",
"person": {
"id": "8d0b6c1e-4f2a-4b7e-9c3d-2a5f1e7b9c40",
"first_name": "Rodney",
"middle_name": null,
"last_name": "Trotter",
"phone_number": "+447700900123",
"email_address": "rodney@trotters.traders",
"date_of_birth": "1988-04-12",
"url": "https://verify.hoxtonmix.com/abc123",
"kyc_checks_passed": false,
"id_verification": {
"status": "APPROVED",
"reason": null
},
"address_verification": {
"status": "DECLINED",
"reason": "Document is older than 3 months."
}
},
"kyc_checks_completed": false,
"updated_at": "2026-10-16T11:15:40Z"
}

The person fields are the same as those returned for each person by Get a Virtual Office Subscription, plus id, id_verification and address_verification. id is our own id for the person and is not returned by that endpoint - use it to tell apart the people on a subscription with more than one.

status is one of:

StatusMeaning
CREATEDThe person has been added but no verification has been set up yet.
NOT_STARTEDA verification link has been issued but the person has not opened it.
STARTEDThe person has started the verification.
SUBMITTEDThe person has submitted their documents and they are being checked.
APPROVEDThe verification has passed.
DECLINEDThe verification has failed - see reason.
RESUBMISSIONThe person needs to submit their documents again - see reason.
EXPIREDThe verification link expired before the person completed it.

SUBMITTED also covers a verification our team is reviewing manually, as there is nothing for you to do while it is with us.

reason is only sent for DECLINED and RESUBMISSION, so that you can chase your customer, and is null for every other status. This applies to the webhook only - the Partner Portal still shows the full detail.

Each payload holds the person's full current status, not only what changed. Use kyc_checks_completed to tell when the whole subscription has passed KYC - it only becomes true once every person has passed. It is as of the last status change: adding or removing a person can also change it, but does not send a webhook on its own.

Webhooks can arrive out of order, for example when an earlier delivery is retried. Use updated_at to keep the most recent status for each person and ignore anything older.

Re-triggering a kyc.updated webhook from the Partner Portal sends its original payload again, unchanged.