Webhooks
ProRequires a Pro or Builder plan
What are Webhooks?
Webhooks let AWSYS.CO push real-time event data to any URL you control — your server, a Zapier endpoint, or a serverless function. Every time a defined event occurs (a link is clicked, created, updated, deleted, expired, or hits a limit), AWSYS.CO sends an HTTP POST request to your endpoint containing a JSON payload with full event details. This enables integrations with CRMs, analytics pipelines, Slack bots, and more without polling the API.
Requirements
Webhooks require a Pro or Builder plan. Pro accounts can create up to 5 webhooks; Builder accounts up to 10. Your endpoint must return a 2xx HTTP status code within 10 seconds, or the delivery is marked as failed and retried.
Step-by-step: Create a webhook
- Go to Settings → Webhooks and click New Webhook.
- Enter the Endpoint URL — the HTTPS URL that will receive the POST request. HTTP URLs are rejected.
- Choose which events to subscribe to. Available events:
link.click,link.created,link.updated,link.deleted,link.expired,link.limit_reached,link.geo_blocked. You can subscribe to multiple events per webhook. - Copy the Signing Secret shown. AWSYS.CO signs every payload with this secret (HMAC-SHA256, header
X-AWSYS-Signature) so your server can verify the request came from us. - Click Save. Use the Send Test Event button to fire a sample payload to your endpoint and confirm it is receiving correctly.
- Monitor delivery status in the Recent Deliveries tab — each delivery shows the HTTP status returned by your server.
Configuration reference
| Event name | Triggered when |
|---|---|
link.click | A visitor clicks the short link (one event per click) |
link.created | A new short link is created |
link.updated | An existing link's settings are changed |
link.deleted | A link is permanently deleted |
link.expired | A link's expiry date is reached |
link.limit_reached | A link's maximum click count is reached |
link.geo_blocked | A visitor from a geo-blocked country attempts to access the link |
Common questions
What happens if my endpoint is down?
AWSYS.CO retries failed deliveries up to 3 times with exponential backoff (5 min, 30 min, 2 hours). After 3 failures, the delivery is marked as permanently failed. You can view and replay failed deliveries from the Recent Deliveries tab.
How do I verify the webhook signature?
Compute HMAC-SHA256 of the raw request body using your signing secret, then compare with the value in the X-AWSYS-Signature header. Reject requests where they don't match. See the API Docs for code examples in Node.js and Python.
Can I use short event names like "click" instead of "link.click"?
No. You must use the full prefixed event names (e.g., link.click). Using short names returns an INVALID_EVENTS error when creating or updating a webhook.
Can I create webhooks via the API?
Yes. Use POST /api/webhooks with a JSON body containing url and events (array of event names). The response includes the auto-generated signing secret — store it securely as it is not shown again.