Webhooks & API Keys
Build custom integrations with the OnCloudWine API and subscribe to webhook events for real-time sync.
When the built-in integrations don't cover what you need, OnCloudWine exposes a public API and a webhook system. Both live under Settings → Organization → Developers.
API keys
API keys authenticate programmatic access to your organization's data via the public API.
Generating a key
Open developer settings
Settings → Organization → Developers → API Keys.
Click Create API Key
Pick a name (so future-you knows what it's for) and a scope.
Copy the secret
The key only shows once. Save it in your secret manager (1Password, Vault, AWS Secrets Manager) immediately.
Use it
Authorize requests with
Authorization: Bearer ock_.... The key is organization-scoped, not user-scoped.
Key scopes
| Scope | What it can do |
|---|---|
| read | GET requests across contacts, releases, products, fulfillments, payments. |
| write | POST/PATCH/DELETE — full mutation access. Use sparingly. |
| webhooks | Manage webhook subscriptions only. Useful for ops tooling. |
Revoking a key
If a key is leaked, revoke it immediately from the API Keys list. Revocation is instant — every in-flight request with the key returns 401 thereafter.
Webhooks
Webhooks send real-time HTTPS POSTs to a URL you provide whenever a specific event happens in OnCloudWine.
Available triggers
| Trigger | Fires when |
|---|---|
| CONTACT_CREATED | A new contact is added (manually, via import, or via integration). |
| CONTACT_UPDATED | Any field on a contact changes — including tag and status changes. |
| CONTACT_DELETED | A contact is deleted (not just CANCELLED — fully removed). |
Release, payment, and fulfillment webhook triggers are on the roadmap. For now, those changes can be polled via the API.
Subscribing to a webhook
Open developer settings
Settings → Organization → Developers → Webhooks.
Click Add Webhook
Enter a destination URL (must be HTTPS) and pick the triggers you want.
Copy the signing secret
Generated for you — used to verify each webhook came from OnCloudWine. Store it alongside your API keys.
Save and test
OnCloudWine sends a test ping to confirm your endpoint accepts the signature. Failures are shown immediately.
Verifying signatures
Each webhook POST includes a X-OnCloudWine-Signature header containing
an HMAC-SHA256 of the request body, signed with your webhook secret.
Verify it before processing:
import crypto from 'node:crypto';
function verifyWebhook(rawBody, header, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(header),
Buffer.from(expected)
);
}Retry behavior
If your endpoint returns a non-2xx response or times out (10 seconds), the webhook is retried with exponential backoff: 1m, 5m, 30m, 2h, 6h, 24h. After 6 failed attempts, the webhook is marked failed and visible in the activity log.
Payload shape
Every webhook has the same envelope:
{
"event": "CONTACT_UPDATED",
"timestamp": "2026-04-26T18:42:13.901Z",
"organizationId": "org_abc123",
"data": {
"id": "ctc_def456",
"firstName": "Alex",
"lastName": "Chen",
"email": "[email protected]",
"status": "ACTIVE",
"...": "..."
}
}The data shape matches the contact object returned by the API's
GET /v1/contacts/:id endpoint.
Cache management
The Developers panel also includes a Clear cache button. OnCloudWine caches certain reads (organization config, integration status) for a few minutes to keep the dashboard snappy. If you've made a configuration change in the underlying system (e.g., updated permissions in Square) and aren't seeing it reflected, click clear cache.
It briefly elevates load on the database. Don't use it as a debugging hammer.
API reference
The full API reference is hosted separately. See api.oncloudwine.com for the OpenAPI spec and per-endpoint documentation. Major resource groups:
- Contacts — list, get, create, update, delete; tags; tasks
- Releases — list, get; payments processing
- Products — list, get; variants and stock
- Fulfillments — list, get; shipments and swaps
- Payments — list, get; refunds