Events Reference

Detailed documentation of all webhook event types, including payload structures and trigger conditions.

Event Overview

Events are the core of webhook notifications. Each event represents a specific action or state change in your Atoship account. Understanding event payloads helps you build robust integrations.

Event Structure

All events follow a consistent structure with the following fields:

id

Unique identifier for the event (evt_xxx)

object

Always "Event"

type

Event type (e.g., "label.purchased")

created_at

ISO 8601 timestamp when event occurred

data.object

The affected resource with current state

data.previous_attributes

Changed fields with previous values (optional)

Label Events

Events related to shipping label lifecycle

label.created

label

Triggered when a new shipping label is created but not yet purchased.

Trigger

A label is created via the API or dashboard

Example Payload

{
  "id": "evt_abc123",
  "object": "Event",
  "type": "label.created",
  "created_at": "2025-01-12T10:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": null,
      "carrier": "USPS",
      "service": "Priority Mail",
      "status": "draft",
      "from_address": {
        "name": "Sender Name",
        "street1": "123 Main St",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001",
        "country": "US"
      },
      "to_address": {
        "name": "Recipient Name",
        "street1": "456 Oak Ave",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      },
      "parcel": {
        "weight": 16.0,
        "length": 10,
        "width": 8,
        "height": 4
      },
      "rate": {
        "amount": "8.95",
        "currency": "USD"
      },
      "created_at": "2025-01-12T10:00:00.000Z"
    }
  }
}

label.purchased

label

Triggered when a shipping label is successfully purchased and ready for use.

Trigger

Payment is processed and label is generated

Example Payload

{
  "id": "evt_def456",
  "object": "Event",
  "type": "label.purchased",
  "created_at": "2025-01-12T10:01:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "carrier": "USPS",
      "service": "Priority Mail",
      "status": "purchased",
      "label_url": "https://atoship.com/api/labels/lbl_xyz789.pdf",
      "label_format": "PDF",
      "cost": {
        "amount": "8.95",
        "currency": "USD"
      },
      "purchased_at": "2025-01-12T10:01:00.000Z"
    },
    "previous_attributes": {
      "status": "draft",
      "tracking_number": null
    }
  }
}

label.voided

label

Triggered when a shipping label is voided/cancelled.

Trigger

Label is voided via API or dashboard

Example Payload

{
  "id": "evt_ghi789",
  "object": "Event",
  "type": "label.voided",
  "created_at": "2025-01-12T12:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "status": "voided",
      "voided_at": "2025-01-12T12:00:00.000Z",
      "void_reason": "Customer request"
    },
    "previous_attributes": {
      "status": "purchased"
    }
  }
}

label.refunded

label

Triggered when a label refund is processed.

Trigger

Refund is approved and processed by the carrier

Example Payload

{
  "id": "evt_jkl012",
  "object": "Event",
  "type": "label.refunded",
  "created_at": "2025-01-15T10:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "status": "refunded",
      "refund": {
        "amount": "8.95",
        "currency": "USD",
        "refunded_at": "2025-01-15T10:00:00.000Z"
      }
    },
    "previous_attributes": {
      "status": "voided"
    }
  }
}

Quick Reference

Event Type	Category	Description
`label.created`	Label Events	Triggered when a new shipping label is created but not yet purchased.
`label.purchased`	Label Events	Triggered when a shipping label is successfully purchased and ready for use.
`label.voided`	Label Events	Triggered when a shipping label is voided/cancelled.
`label.refunded`	Label Events	Triggered when a label refund is processed.
`tracking.created`	Tracking Events	Triggered when tracking is initiated for a shipment.
`tracking.updated`	Tracking Events	Triggered when the tracking status changes.
`tracking.delivered`	Tracking Events	Triggered when a package is successfully delivered.
`tracking.exception`	Tracking Events	Triggered when a tracking exception occurs (delay, return to sender, etc.).
`batch.created`	Batch Events	Triggered when a new batch operation is created.
`batch.completed`	Batch Events	Triggered when a batch operation completes successfully.
`batch.failed`	Batch Events	Triggered when a batch operation fails completely.
`scan_form.created`	Scan Form Events	Triggered when a new SCAN form is created.
`scan_form.updated`	Scan Form Events	Triggered when a SCAN form status is updated.
`payment.created`	Payment Events	Triggered when a payment/charge is initiated.
`payment.completed`	Payment Events	Triggered when a payment is successfully completed.
`payment.failed`	Payment Events	Triggered when a payment fails.
`return.created`	Return Events	Triggered when a return label or RMA is created.
`return.received`	Return Events	Triggered when a return package is received at the warehouse.
`return.completed`	Return Events	Triggered when a return is fully processed.
`insurance.purchased`	Insurance Events	Triggered when insurance is purchased for a shipment.
`insurance.cancelled`	Insurance Events	Triggered when insurance is cancelled.
`claim.created`	Claim Events	Triggered when an insurance claim is filed.
`claim.approved`	Claim Events	Triggered when an insurance claim is approved.
`claim.rejected`	Claim Events	Triggered when an insurance claim is rejected.