Everything you need to integrate with the Ballpoint Marketing direct mail API: ordering, real-time tracking, billing, and webhook delivery.
START_HERE.md — Zero to a working test order in under 5 minutes.
| Resource | Description |
|---|---|
| API Integration Kit | Full integration guide: auth, endpoints, webhooks, error handling |
| OpenAPI Spec | Machine-readable API specification (import into Postman, Swagger UI, etc.) |
| Quick Start Guide | Step-by-step first-order walkthrough |
| Example | Description |
|---|---|
| Postman Collection | Pre-built requests for every endpoint |
| Express Integration | Node.js/Express webhook receiver with signature verification |
| Lambda Webhook | AWS Lambda handler for webhook processing |
| Cloudflare Worker | Cloudflare Worker webhook receiver |
- Sandbox — for testing
- Production — for live traffic
All webhook payloads are signed with HMAC-SHA256. Your integration must verify signatures before processing events.
| Header | Purpose |
|---|---|
X-Ballpoint-Signature |
sha256=<hex> — HMAC of timestamp + raw body using your webhook secret |
X-Ballpoint-Timestamp |
ISO 8601 timestamp — reject if older than 5 minutes (replay protection) |
X-Ballpoint-Event-Id |
Unique event ID — store and check for deduplication |
Idempotency-Key |
Required on POST /v1/billing/orders — prevents duplicate orders on retry |
See the API Integration Kit for full verification examples and the webhook receiver templates in examples/ for working implementations.
For API access, environment keys, and technical support, reach out to your partner technical contact at Ballpoint.