Realtime Events
Subscribe to real-time upload events over Socket.IO. Receive instant notifications as images are uploaded, delivered, or fail.
Connection
/socket.io → namespace /uploadOpen a Socket.IO connection to the /upload namespace, then emit session:join with the session UUID. The UUID itself is the access token, so no API key is sent on the socket. The server pushes events into the session room as they occur.
Native Socket.IO clients only
Realtime events require a native Socket.IO client — available for JavaScript, Python, and Java. Languages without one (Go, Rust, PHP, Ruby, Perl) should use event webhooks or long polling instead.
Event Types
| Event | Description |
|---|---|
| image:ready | A new image has been uploaded and is ready for processing |
| image:delivering | An image is being delivered to a destination |
| image:delivered | An image has been delivered to a destination |
| image:failed | An image delivery attempt has failed |
Subscribing
Connect using the Node.js SDK or any native Socket.IO client (browser, Python, Java).
import { Apertur } from '@apertur/sdk';
const client = new Apertur({ apiKey: 'aptr_live_xxxx' });
// Opens a Socket.IO connection and joins the session room.
const events = client.events.subscribe('sess_01HX...');
events.on('connected', (data) => {
console.log('Joined session:', data.sessionId);
});
events.on('image:ready', (data) => {
console.log('Image ready:', data);
});
events.on('image:delivered', (data) => {
console.log('Delivered to:', data.destinationId);
});
events.on('image:failed', (data) => {
console.error('Delivery failed:', data);
});
events.on('error', (err) => console.error('Socket error:', err));
// Stop listening when you're done.
// events.close();Reconnection
Socket.IO reconnects automatically if the connection drops. On each reconnect the client re-emits session:join, so it resumes receiving events without re-subscribing.
Note
Events are live-only — they are not replayed for the window a client was disconnected. For guaranteed, at-least-once delivery, use event webhooks instead.