Webhooks

Alto webhooks let your integration receive real-time notifications when relevant data changes in Alto, so you no longer have to poll our APIs to detect updates.

When something happens in Alto that you have subscribed to — for example a property is modified or a new contact is created — Alto sends an HTTP POST request to an endpoint that you host. The request body describes what changed and gives you the information you need to retrieve the latest data from the relevant API.

Before you begin

Webhooks build on top of your existing API integration. Before subscribing to webhooks you should already have:

• A live integration created via the Developer Portal.
• Working authentication against the Alto APIs (see Authenticating your Requests).
• An HTTPS endpoint that you control and that is reachable from the public internet.

Webhook subscriptions are configured by the Alto team on your behalf. To request a subscription, email connectsupport@altosoftwaregroup.co.uk with your Integration Name, the URL of your receiving endpoint, the event types you want to subscribe to, and your preferred authentication method (see Securing your endpoint).

How it works

1. An action takes place in Alto (for example, an agent modifies a property).
2. Alto raises an internal event describing the change.
3. If your integration is subscribed to that event type, Alto sends a notification to your endpoint.
4. Your endpoint receives the notification and, if required, calls the relevant Alto API to fetch the full, up-to-date resource.

Notifications are intentionally lightweight. Rather than embedding the full changed record, each notification tells you what changed and where to find it, so you can then retrieve exactly the data you need from the appropriate API. This keeps payloads small and ensures you always read the current state of the resource.

Notification format

Notifications follow the CloudEvents 1.0 specification and are sent as JSON with a Content-Type of application/json.

An example notification for a modified property:

{
  "specversion": "1.0",
  "id": "b1e9b0f0-1c2d-4e3f-9a8b-7c6d5e4f3a2b|11111111-2222-3333-4444-555555555555",
  "type": "Property.Modified",
  "source": "alto",
  "subject": "/inventory/123456",
  "time": "2024-01-30T15:51:40Z",
  "datacontenttype": "application/json",
  "data": {
    "integrationId": "11111111-2222-3333-4444-555555555555",
    "agencyRef": "YOUR_AGENCY_REF",
    "branchId": "2681",
    "subjectId": "123456",
    "relatedSubjects": []
  }
}

Top-level fields

Field	Description
specversion	The CloudEvents specification version. Always 1.0.
id	A unique identifier for this notification.
type	The event type that was raised (see Event types).
source	The system that produced the event. Always alto.
subject	A relative URI identifying the resource that changed.
time	The time the originating change occurred, in UTC (ISO 8601).
datacontenttype	The media type of the data field. Always application/json.
data	An object containing the details you need to identify and retrieve the resource. See below.

The data object

Field	Description
integrationId	The identifier of your integration. Useful when a single endpoint serves more than one integration.
agencyRef	The agency reference associated with the change. Use this as the AgencyRef header when calling Alto APIs.
branchId	The identifier of the branch the resource belongs to, where applicable.
subjectId	The identifier of the resource that changed. This is also the final segment of the subject URI.
relatedSubjects	An array of related resources, each with its own subjectUri and subjectId. May be empty.

The subject field is a relative URI. To retrieve the full resource, combine it with the Alto API base URL and call the endpoint using your usual authentication. For example, a subject of /inventory/123456 corresponds to the inventory endpoint for property 123456 in the API Reference.

Event types

You can subscribe to any combination of the event types below. Each event’s subject points at the resource that changed.

Event type	Raised when	Subject resource
Contact.Created	A contact is created	Contact
Contact.Modified	A contact is modified	Contact
Property.Created	A property is created	Property
Property.Modified	A property is modified	Property
Property.MarketingInformationSent	Marketing information is sent for a property	Property
Branch.Modified	A branch is modified	Branch
Appointment.Created	An appointment is created	Appointment
Appointment.Modified	An appointment is modified	Appointment
Tenancy.Created	A tenancy is created	Tenancy
Tenancy.Modified	A tenancy is modified	Tenancy
Tenancy.ReferencingPassed	A tenancy passes referencing	Tenancy
Tenancy.Renewed	A tenancy is renewed	Tenancy
Tenancy.Vacated	A tenancy is vacated	Tenancy
Offer.Created	An offer is created	Offer / Sales Progression
Offer.Modified	An offer is modified	Offer / Sales Progression
Offer.Accepted	An offer is accepted	Sales Progression
Offer.Withdrawn	An offer is withdrawn	Offer / Sales Progression
SalesProgression.Exchanged	A sale reaches exchange	Sales Progression
SalesProgression.Milestone.Completed	A sales progression milestone is completed	Sales Progression
Lead.Received	A lead is received	Lead
Lead.Accepted	A lead is accepted	Lead
Lead.Modified	A lead is modified	Lead
Integration.Enabled	Your integration is enabled for a group	Integration
Integration.Disabled	Your integration is disabled for a group	Integration
Integration.Activated	Your integration is activated for a branch	Integration
Integration.Deactivated	Your integration is deactivated for a branch	Integration

If you would like to see an event type that is not listed here, let us know via connectsupport@altosoftwaregroup.co.uk.

Securing your endpoint

Your endpoint is called over HTTPS only. When we set up your subscription, we agree one of the following authentication methods so that your endpoint can verify that a request genuinely came from Alto:

• API key — Alto sends a shared secret in an x-signature request header. Your endpoint rejects any request that does not present the expected value.
• Basic authentication — Alto sends a username and password using HTTP Basic authentication.
• OAuth 2.0 (client credentials) — Alto obtains a bearer token from your authorization server using the client credentials grant and presents it on each request.

Credentials are exchanged securely during onboarding and are never included in the notification payload. We recommend rotating them periodically; contact us to arrange a rotation.

Responding to notifications

Your endpoint should return a 2xx HTTP status code to acknowledge that a notification has been received. Aim to acknowledge quickly and do any heavier processing asynchronously.

Retries

If your endpoint does not return a 2xx response — for example because it is unreachable, returns an error, or times out — Alto automatically retries delivery. Delivery is retried up to 10 times and notifications are retried for up to 6 hours from when the change occurred. After this window a notification is no longer retried.

Because delivery is retried, your endpoint may occasionally receive the same notification more than once. You should design your endpoint to be idempotent — processing the same notification twice should have the same effect as processing it once. The id field is stable across retries of the same notification and can be used for de-duplication.

Ordering

Notifications are delivered as soon as possible after a change, but delivery order is not guaranteed. Do not rely on the order in which notifications arrive. Because each notification points you at the current resource rather than embedding a snapshot, fetching the resource on receipt always gives you the latest state.

Best practices

• Always re-fetch. Treat a notification as a signal that something changed, then call the relevant API to read the current resource. Do not treat the payload as a complete record of the change.
• Be idempotent. Use the id field to guard against processing duplicate deliveries.
• Acknowledge fast. Return a 2xx promptly and process asynchronously to avoid timeouts and unnecessary retries.
• Handle unknown fields gracefully. We may add fields to the payload over time. Ignore any fields you do not recognise rather than failing.
• Filter by type and integrationId. If one endpoint serves multiple integrations or event types, use these fields to route each notification correctly.

Getting help

To set up, change, or troubleshoot a webhook subscription, contact us at connectsupport@altosoftwaregroup.co.uk with your Integration Name.