Cothery Developer Portal
Integrate Cothery licensing into your products. Verify purchases, manage activations, and automate your workflow with our API and webhooks.
Webhooks
Receive real-time notifications when events occur on your products
How Webhooks Work
Webhooks let you receive HTTP POST requests to your server whenever events happen on Cothery — like a new purchase, a refund, or a license activation. This lets you automate workflows without polling the API.
Event Occurs
Customer buys, refunds, or activates
We Send a POST
JSON payload to your endpoint
You Process It
Respond with 200 OK
Setting Up Webhooks
Go to Vendor Dashboard → Settings
Navigate to the Webhooks section in your vendor settings.
Enter your endpoint URL
Must be a publicly accessible HTTPS URL, e.g. https://yoursite.com/webhooks/cothery
Copy your Webhook Secret
Use this secret to verify that incoming requests are from Cothery (see signature verification below).
Select events to subscribe to
Choose which events trigger a webhook call.
Available Events
order.completed
Fired when a customer completes a purchase of your product.
order.refunded
Fired when a refund is issued for an order containing your product.
license.activated
Fired when a license key for your product is activated via the API.
license.deactivated
Fired when a license key is deactivated via the API.
license.suspended
Fired when a license key is suspended by an admin.
license.expired
Fired when a license key reaches its expiration date.
review.created
Fired when a customer leaves a review on your product.
dispute.opened
Fired when a customer opens a dispute on an order with your product.
Payload Example
Example payload for order.completed
{
"event": "order.completed",
"timestamp": "2026-03-01T14:32:00Z",
"data": {
"order": {
"id": 1234,
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"total_cents": 4900,
"currency": "USD"
},
"customer": {
"name": "Jane Smith",
"email": "jane@example.com"
},
"items": [
{
"product_id": 42,
"product_name": "My Awesome Script",
"license_type": "regular",
"license_key": "XXXX-XXXX-XXXX-XXXX",
"price_cents": 4900
}
]
}
}
Signature Verification
Every webhook request includes a X-Cothery-Signature header. Verify this signature to ensure the request genuinely came from Cothery.
PHP Example
$payload = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_COTHERY_SIGNATURE']; $secret = 'your-webhook-secret'; $expected = hash_hmac('sha256', $payload, $secret); if (hash_equals($expected, $signature)) { // Signature is valid — process the webhook $data = json_decode($payload, true); // ... handle the event } else { http_response_code(401); exit('Invalid signature'); }
Always verify signatures
Never process webhook payloads without verifying the signature. This prevents attackers from sending fake events to your endpoint.
Retry Policy
If your endpoint doesn't respond with a 2xx status code within 30 seconds, we'll retry delivery with exponential backoff:
| Attempt | Delay | Total Wait |
|---|---|---|
| 1st retry | 1 minute | ~1 min |
| 2nd retry | 5 minutes | ~6 min |
| 3rd retry | 30 minutes | ~36 min |
| 4th retry | 2 hours | ~2.5 hrs |
| 5th retry (final) | 24 hours | ~26.5 hrs |
After 5 failed attempts, the webhook delivery is marked as failed. You can view and retry failed deliveries from your Vendor Dashboard.