Overview
Aptem webhooks allow you to receive real-time notifications when records are created or updated for supported entities. These notifications are sent to an external service (a “webhook receiver”) that you own and maintain.
Important:
- You cannot configure webhooks to trigger on specific fields only.
- You cannot disable individual event types (Create or Update).
- Webhook payloads contain a full data snapshot, not a list of changes.
Supported event types
The following event types are supported:
- Create - when a new record is created.
- Update - when an existing record is updated.
The Delete event type is not supported.
Supported entities
Webhooks are available for the following entities:
- User (Learner / Participant only — excludes Admins, Employers, etc.)
- Tracker
- ILR
- Job
Configuration
To enable webhooks for your tenant, ensure that:
- The webhooks module is enabled by the Support team.
- The webhooks token is enabled in the account programme.
- A webhook is configured with a target URL and entity type.
Subscribe
To set up a webhook:
- Select a Webhook Type (entity you want notifications for)
- Provide a Webhook URL (your external receiver service)
- (Optional) Add custom headers
Custom headers
- Format:
HeaderName: Value - Header names are converted to lowercase and trimmed
- Values are trimmed but preserve original casing
- Multiple headers can be added (one per line)
Note:
Only one webhook can be configured per entity. Attempting to create multiple webhooks for the same entity will result in an error.
Unsubscribe
To stop receiving webhook notifications for an entity:
- Remove the webhook configuration from the webhooks token in the account programme.
Important:
Disabling the webhooks token alone does not stop notifications if a configuration still exists.
Payload and headers
Webhook requests follow this structure:
{ "headers": { ... }, "body": { ... }}
Headers
Each request includes:
Last-Modified— timestamp of the update (RFC1123 format)Content-Type: application/json- Any custom headers you configured
Body
The body contains a snapshot of the entity data at the time of the event. The exact fields depend on the entity type.
Retries
After sending a webhook, Aptem expects a 200 OK response from your service.
If any other response is returned:
- The webhook will be retried up to 10 times.
- Retries use a progressive delay.
- The final attempt occurs approximately 4–5 hours after the initial request.