Skip to main content
Webhooks let your systems react to token lifecycle events the moment they happen. When an event occurs — a token is revoked, rotated, or expires — Tooken sends an HTTP POST request to a URL you configure, with a signed JSON payload describing the event. This is more efficient than polling the API and lets you trigger downstream workflows, alert systems, or audit pipelines in real time.

​
Supported events

EventDescription
token.createdA new token was issued in your workspace.
token.revokedA token was explicitly revoked by a user or via the API.
token.rotatedA token’s secret was rotated. The token ID remains the same.
token.expiredA token’s expiration date passed and it is no longer valid.
token.expiringA token is approaching its expiration date. Tooken fires this event 7 days and 1 day before expires_at. Use it to trigger alerts or automated rotation.
token.usedA token was used to authenticate a request. This is a high-volume event — opt in only if your endpoint can handle the throughput.

​
Create a webhook

1

Open Webhooks settings

In the Tooken dashboard, click Settings in the left sidebar, then select the Webhooks tab.
2

Click New Webhook

Click the New Webhook button in the top-right corner.
3

Enter your endpoint URL

Paste the full HTTPS URL where Tooken should send event payloads. The endpoint must be publicly reachable and able to accept POST requests.
4

Select events

Check the events you want this webhook to receive. You can subscribe a single endpoint to multiple events, or create separate webhooks for different event types.
5

Save

Click Save. Tooken generates a webhook secret and displays it once — copy it now and store it securely. You will use it to verify incoming requests.

​
Webhook payload

Every event Tooken sends follows the same envelope structure: a top-level event name, a timestamp in ISO 8601 UTC, and a data object with the relevant resource fields. Below is an example payload for a token.revoked event: 
{
  "event": "token.revoked",
  "timestamp": "2024-06-01T14:00:00Z",
  "data": {
    "id": "tok_a1b2c3d4e5f6g7h8i9j0k1l2",
    "name": "ci-deploy-bot",
    "revoked_by": "user_abc123"
  }
}
The fields in data vary by event type. For token.created, data includes id, name, created_by, and expires_at. For token.expired, data includes id, name, and expired_at. Refer to the API reference for full details.

​
Verify webhook signatures

Tooken signs every webhook request with an X-Tooken-Signature header. The value is an HMAC-SHA256 hex digest of the raw request body, computed using the webhook secret generated when you created the endpoint.
Always verify the signature before processing a webhook payload. Without verification, your endpoint could be triggered by forged requests from any source, not just Tooken.
Compare the header value against a signature you compute server-side. If they do not match, reject the request with a 400 status and do not process the payload. 
const crypto = require('crypto');

function verifyWebhook(req) {
  const sig = req.headers['x-tooken-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest('hex');

  if (sig !== expected) {
    throw new Error('Invalid signature');
  }
}
Use req.rawBody (the unparsed request body as a Buffer or string), not a parsed JSON object. Parsing the body before hashing changes the byte content and will cause the comparison to fail.

​
Retries

If your endpoint does not return a 2xx status within 10 seconds, Tooken marks the delivery as failed and schedules a retry.
Your endpoint must respond with a 2xx status code within 10 seconds. If it times out or returns a non-2xx response, Tooken treats the delivery as failed and will retry according to the schedule below.
Tooken retries failed deliveries up to 5 times using exponential backoff:
AttemptDelay after previous failure
1st retry1 second
2nd retry5 seconds
3rd retry30 seconds
4th retry2 minutes
5th retry10 minutes
After 5 failed attempts, Tooken stops retrying and marks the delivery as permanently failed. You can view delivery history and manually trigger a redeliver from Settings → Webhooks → [your webhook] → Delivery logs.
Because Tooken retries on failure, your endpoint may receive the same event more than once. Use the payload’s data.id field (the token ID) and the event name together as a deduplication key. Store processed event IDs in your database and skip any delivery where that combination has already been handled.
Yes. When creating or editing a webhook via the API, pass "events": ["*"] to subscribe to all current and future event types. In the dashboard, check All events when selecting events for the webhook.
Use a tool like ngrok to create a public HTTPS tunnel to your local server, then register that URL as your webhook endpoint. From Settings → Webhooks, you can also click Send test event to push a sample payload to your endpoint without waiting for a real event to occur.
Yes. From Settings → Webhooks, toggle the webhook’s status to Inactive. Tooken will stop sending deliveries to the endpoint until you reactivate it. No deliveries are queued while the webhook is inactive.