Webhooks Guide

Receive real-time events when links are clicked or modified

Webhooks allow your server to receive HTTP POST notifications from AWSYS.CO whenever specific events occur on your links. Use them to trigger workflows, update dashboards, or sync data to external systems in real time.

Create a Webhook

POST /api/webhooks

Request body

{
  "url": "https://your-server.com/webhooks/awsys",
  "events": ["link.click", "link.created"],
  "secret": "your-signing-secret"
}

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint that will receive POST requests
`events`	string[]	Yes	List of event names to subscribe to (full names required — see table below)
`secret`	string	No	Signing secret used to verify the `X-Awsys-Signature` header on each delivery

Supported Events

Use the full event name. Short names (e.g. click instead of link.click) return an INVALID_EVENTS error and the webhook will not be created.

Event	Description
`link.click`	A short link was clicked by a visitor
`link.created`	A new short link was created in your account
`link.updated`	A short link's destination or settings were modified
`link.deleted`	A short link was permanently deleted
`link.expired`	A short link's expiry date was reached and the link is now inactive
`link.limit_reached`	A short link hit its click limit and will no longer redirect
`link.geo_blocked`	A visitor was blocked from accessing a link due to geo-restriction rules

Event Payload

AWSYS.CO delivers a JSON payload via HTTP POST to your endpoint. Here is an example payload for a link.click event:

{
  "event": "link.click",
  "timestamp": "2026-05-25T14:32:01Z",
  "data": {
    "shortCode": "abc123",
    "url": "https://awsys.co/abc123",
    "destination": "https://example.com/landing-page",
    "country": "US",
    "device": "mobile",
    "referrer": "twitter.com",
    "userAgent": "Mozilla/5.0 ..."
  }
}

Signature Verification

Every delivery includes an X-Awsys-Signature header containing an HMAC-SHA256 signature of the raw request body, computed using your webhook secret. Always verify this signature before processing the payload.

const crypto = require('crypto');

function verifySignature(rawBody, secret, signatureHeader) {
  const sig = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  if (sig !== signatureHeader) {
    throw new Error('Invalid signature');
  }
}

// Express.js example
app.post('/webhooks/awsys', express.raw({ type: 'application/json' }), (req, res) => {
  verifySignature(
    req.body,
    process.env.WEBHOOK_SECRET,
    req.headers['x-awsys-signature']
  );
  const event = JSON.parse(req.body);
  // handle event...
  res.sendStatus(200);
});

Use express.raw(), not express.json(), when receiving webhook payloads. The HMAC signature is computed over the raw bytes — parsing to JSON first changes the byte representation and will cause verification to fail.

Retry Behavior

If your endpoint does not return a 2xx status code within 10 seconds, AWSYS.CO will retry delivery up to 3 times using exponential backoff:

Attempt	Delay after previous failure
1st retry	30 seconds
2nd retry	5 minutes
3rd retry	30 minutes

After 3 failed retries the delivery is abandoned. Make your endpoint idempotent — the same event may be delivered more than once if a retry occurs after your server processed but failed to acknowledge the request.

curl example — create a webhook

curl -X POST https://awsys.co/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/awsys",
    "events": ["link.click", "link.created", "link.deleted"],
    "secret": "your-signing-secret"
  }'