Webhook Event Types
Webhooks allow you to receive real-time notifications when events occur in your atoship account. Configure webhook endpoints to listen for specific event types.
Signature Verification
All webhook requests include a signature header for verification. Verify the signature by computing HMAC-SHA256 of the raw request body using your webhook secret.
X-Atoship-Signature: sha256=abc123...Available Events
Label Events
Events related to shipping label lifecycle
label.createdTriggered when a new shipping label is successfully purchased
label.voidedTriggered when a shipping label is voided/cancelled
label.refundedTriggered when a label refund is processed
Tracking Events
Events related to package tracking updates
tracking.updatedTriggered when tracking status changes for a shipment
tracking.deliveredTriggered when a package is successfully delivered
tracking.exceptionTriggered when a delivery exception occurs
tracking.return_to_senderTriggered when a package is being returned to sender
Insurance Events
Events related to shipping insurance
insurance.purchasedTriggered when insurance is purchased for a shipment
insurance.claim.filedTriggered when an insurance claim is filed
insurance.claim.approvedTriggered when an insurance claim is approved
insurance.claim.deniedTriggered when an insurance claim is denied
Return Events
Events related to return shipments
return.createdTriggered when a return label is created
return.in_transitTriggered when a return package is in transit
return.receivedTriggered when a return package is received
Account Events
Events related to account and billing
account.balance.lowTriggered when account balance falls below threshold
account.balance.depletedTriggered when account balance reaches zero
Best Practices
Return a 200 status within 30 seconds to acknowledge receipt
Use the event ID to deduplicate events
Always validate the webhook signature before processing
Failed webhooks are retried up to 5 times with exponential backoff
| 1 | { |
| 2 | "id": "evt_1234567890", |
| 3 | "object": "Event", |
| 4 | "type": "label.created", |
| 5 | "created_at": "2025-01-14T10: 00: 00Z", |
| 6 | "data": { |
| 7 | "id": "lbl_k7x9m2p4q8r5", |
| 8 | "object": "Label", |
| 9 | "status": "purchased", |
| 10 | "tracking_number": "9400111899223456789012", |
| 11 | "carrier": "USPS", |
| 12 | "service": "Priority Mail", |
| 13 | "rate": 8.95, |
| 14 | "currency": "USD" |
| 15 | } |
| 16 | } |