Webhook Payload Format

Complete reference for webhook payload structure.

Payload Structure

All webhook payloads follow this structure:

{
  "id": "event-uuid",
  "event": "order.delivered",
  "payload": {
    // Event-specific data
  },
  "at": "2026-08-19T10:30:00.000Z"
}

Top-Level Fields

Field	Type	Description
`id`	string	Unique event ID (use for idempotency)
`event`	string	Event type (e.g., `order.delivered`)
`payload`	object	Event-specific data
`at`	string	Event timestamp (ISO 8601)

Common Payload Fields

Order Fields

Most order events include these fields:

{
  "id": "order-uuid",
  "status": "delivered",
  "externalRef": "YANGO-ORDER-123",
  "courimaxOrderId": "order-uuid",
  "pickupAddress": "Rothschild Blvd 1, Tel Aviv",
  "pickupLat": 32.0639,
  "pickupLng": 34.7742,
  "dropoffAddress": "Dizengoff Center, Tel Aviv",
  "dropoffLat": 32.0753,
  "dropoffLng": 34.7749,
  "recipientName": "Jane Doe",
  "recipientPhone": "+972501234567",
  "packageSize": "small",
  "trackingToken": "tracking-token-abc",
  "createdAt": "2026-08-19T10:00:00.000Z",
  "updatedAt": "2026-08-19T10:30:00.000Z"
}

Field	Type	Description
`id`	string	Courimax order ID
`status`	string	Current order status
`externalRef`	string	Your order reference
`courimaxOrderId`	string	Courimax internal order ID
`pickupAddress`	string	Pickup address
`pickupLat`	number	Pickup latitude
`pickupLng`	number	Pickup longitude
`dropoffAddress`	string	Dropoff address
`dropoffLat`	number	Dropoff latitude
`dropoffLng`	number	Dropoff longitude
`recipientName`	string	Recipient name
`recipientPhone`	string	Recipient phone
`packageSize`	string	Package size
`trackingToken`	string	Public tracking token
`createdAt`	string	Order creation timestamp
`updatedAt`	string	Last update timestamp

Driver Fields

Events involving driver assignment include:

{
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen",
    "phone": "+972501234567"
  }
}

Field	Type	Description
`driver.id`	string	Driver ID
`driver.name`	string	Driver name
`driver.phone`	string	Driver phone

Location Fields

Events with driver location include:

{
  "driverLocation": {
    "latitude": 32.07,
    "longitude": 34.78,
    "accuracy": 10,
    "timestamp": "2026-08-19T10:20:00.000Z"
  }
}

Field	Type	Description
`latitude`	number	GPS latitude
`longitude`	number	GPS longitude
`accuracy`	number	GPS accuracy in meters
`timestamp`	string	Location timestamp

Proof of Delivery

Delivered events include proof of delivery:

{
  "proofOfDelivery": {
    "recipientNameConfirmed": "Jane Doe",
    "gpsLat": 32.0753,
    "gpsLng": 34.7749,
    "photoUrl": "https://storage.courimax.com/pod/photo.jpg",
    "signatureUrl": "https://storage.courimax.com/pod/signature.jpg",
    "deliveredAt": "2026-08-19T10:30:00.000Z"
  }
}

Field	Type	Description
`recipientNameConfirmed`	string	Confirmed recipient name
`gpsLat`	number	Delivery GPS latitude
`gpsLng`	number	Delivery GPS longitude
`photoUrl`	string	Delivery photo URL (optional)
`signatureUrl`	string	Signature image URL (optional)
`deliveredAt`	string	Delivery timestamp

Event-Specific Payloads

order.created

{
  "id": "order-uuid",
  "status": "pending",
  "externalRef": "YANGO-ORDER-123",
  "pickupAddress": "Rothschild Blvd 1, Tel Aviv",
  "dropoffAddress": "Dizengoff Center, Tel Aviv",
  "recipientName": "Jane Doe",
  "recipientPhone": "+972501234567",
  "packageSize": "small",
  "createdAt": "2026-08-19T10:00:00.000Z"
}

order.assigned

{
  "id": "order-uuid",
  "status": "assigned",
  "externalRef": "YANGO-ORDER-123",
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen",
    "phone": "+972501234567"
  },
  "assignedAt": "2026-08-19T10:05:00.000Z"
}

order.picked_up

{
  "id": "order-uuid",
  "status": "picked_up",
  "externalRef": "YANGO-ORDER-123",
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen"
  },
  "pickedUpAt": "2026-08-19T10:15:00.000Z"
}

order.in_transit

{
  "id": "order-uuid",
  "status": "in_transit",
  "externalRef": "YANGO-ORDER-123",
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen"
  },
  "driverLocation": {
    "latitude": 32.07,
    "longitude": 34.78
  },
  "inTransitAt": "2026-08-19T10:20:00.000Z"
}

order.delivered

{
  "id": "order-uuid",
  "status": "delivered",
  "externalRef": "YANGO-ORDER-123",
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen"
  },
  "deliveredAt": "2026-08-19T10:30:00.000Z",
  "proofOfDelivery": {
    "recipientNameConfirmed": "Jane Doe",
    "gpsLat": 32.0753,
    "gpsLng": 34.7749,
    "photoUrl": "https://storage.courimax.com/pod/photo.jpg",
    "signatureUrl": "https://storage.courimax.com/pod/signature.jpg"
  }
}

order.failed

{
  "id": "order-uuid",
  "status": "failed",
  "externalRef": "YANGO-ORDER-123",
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen"
  },
  "failedAt": "2026-08-19T10:30:00.000Z",
  "failureReason": "Customer not available",
  "notes": "Attempted delivery 3 times"
}

order.cancelled

{
  "id": "order-uuid",
  "status": "cancelled",
  "externalRef": "YANGO-ORDER-123",
  "cancelledAt": "2026-08-19T10:10:00.000Z",
  "reason": "Customer requested cancellation"
}

TypeScript Types

interface WebhookEvent {
  id: string;
  event: WebhookEventType;
  payload: OrderPayload;
  at: string;
}

type WebhookEventType =
  | 'order.created'
  | 'order.assigned'
  | 'order.picked_up'
  | 'order.in_transit'
  | 'order.delivered'
  | 'order.failed'
  | 'order.cancelled';

interface OrderPayload {
  id: string;
  status: OrderStatus;
  externalRef: string;
  courimaxOrderId?: string;
  pickupAddress?: string;
  pickupLat?: number;
  pickupLng?: number;
  dropoffAddress?: string;
  dropoffLat?: number;
  dropoffLng?: number;
  recipientName?: string;
  recipientPhone?: string;
  packageSize?: string;
  trackingToken?: string;
  driver?: Driver;
  driverLocation?: Location;
  proofOfDelivery?: ProofOfDelivery;
  createdAt?: string;
  updatedAt?: string;
  assignedAt?: string;
  pickedUpAt?: string;
  inTransitAt?: string;
  deliveredAt?: string;
  failedAt?: string;
  cancelledAt?: string;
  failureReason?: string;
  reason?: string;
  notes?: string;
}

interface Driver {
  id: string;
  name: string;
  phone: string;
}

interface Location {
  latitude: number;
  longitude: number;
  accuracy?: number;
  timestamp?: string;
}

interface ProofOfDelivery {
  recipientNameConfirmed: string;
  gpsLat: number;
  gpsLng: number;
  photoUrl?: string;
  signatureUrl?: string;
  deliveredAt: string;
}

type OrderStatus =
  | 'pending'
  | 'dispatching'
  | 'assigned'
  | 'picked_up'
  | 'in_transit'
  | 'delivered'
  | 'failed'
  | 'cancelled';

Validation

Validate webhook payloads using TypeScript or a validation library:

const Joi = require('joi');

const webhookSchema = Joi.object({
  id: Joi.string().uuid().required(),
  event: Joi.string().valid(
    'order.created',
    'order.assigned',
    'order.picked_up',
    'order.in_transit',
    'order.delivered',
    'order.failed',
    'order.cancelled'
  ).required(),
  payload: Joi.object().required(),
  at: Joi.date().iso().required()
});

app.post('/webhooks/courimax', (req, res) => {
  const { error } = webhookSchema.validate(req.body);
  
  if (error) {
    logger.error('Invalid webhook payload', error);
    return res.status(400).send('Invalid payload');
  }
  
  handleWebhook(req.body);
  res.status(200).send('OK');
});

Next Steps

Event Types - Complete list of events
Webhooks Overview - Configuration and security

Payload Structure​

Top-Level Fields​

Common Payload Fields​

Order Fields​

Driver Fields​

Location Fields​

Proof of Delivery​

Event-Specific Payloads​

order.created​

order.assigned​

order.picked_up​

order.in_transit​

order.delivered​

order.failed​

order.cancelled​

TypeScript Types​

Validation​

Next Steps​