Skip to content
Astratva
Search
Colour mode: Light Colour mode: Dark Colour mode: System
English, Language
Sign in
Menu

Developers

Webhooks

Astratva posts a signed JSON event to your HTTPS endpoint when something happens to your API account. You register endpoints on your developer page, within the limit of your plan.

What a delivery looks like

Each delivery is a POST with a JSON body of three fields: id (the event), type and data. Your endpoint answers any 2xx status to confirm it. Anything else, or no answer within 10 seconds, is retried after one and five minutes; after 20 events in a row fail that way the endpoint is disabled and you are emailed once. Redirects are not followed: a 3xx answer counts as a failure.

Endpoints must be HTTPS on port 443 at a domain name that resolves to public addresses. The address is checked when you register the endpoint and again before every delivery, and private, loopback, link-local and cloud metadata addresses are refused.

Content-Type: application/json
X-Webhook-Id: 7d1c1a5e-3b0e-4f0a-9d6e-0c9a52f3d1aa
X-Webhook-Timestamp: 1794567890
X-Webhook-Signature: 5b0c…(64 hex characters)
  • X-Webhook-Id: the delivery id. It is part of the signed string. Keep the ones you have handled: delivery is at least once, so the same delivery can arrive again.
  • X-Webhook-Timestamp: when this attempt was signed, in Unix seconds.
  • X-Webhook-Signature: the HMAC-SHA256, as lowercase hexadecimal with no prefix.

Verify the signature

The signature is HMAC-SHA256(secret, timestamp.deliveryId.body): the timestamp, a full stop, the delivery id, a full stop, then the body exactly as received. In the formula, timestamp.deliveryId.body means the three values joined by full stops. Compute it over the raw bytes, before you parse the JSON, and compare in constant time.

Reject a delivery whose timestamp is more than five minutes from your clock. A signed request that is captured cannot then be replayed later. Keep your clock synchronised.

PHP

<?php
// $secret is the endpoint secret shown once when you registered or rotated it.
$body      = file_get_contents('php://input');           // the exact bytes, before any JSON decoding
$id        = $_SERVER['HTTP_X_WEBHOOK_ID'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $timestamp.'.'.$id.'.'.$body, $secret);

if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300 || ! hash_equals($expected, $signature)) {
    http_response_code(400);
    exit;
}
// Deliveries are at least once: skip an $id you have already handled.
http_response_code(200);

Node.js

// Express: read the raw body, not the parsed one.
import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/astratva-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const id = req.get('X-Webhook-Id') ?? '';
  const timestamp = req.get('X-Webhook-Timestamp') ?? '';
  const signature = req.get('X-Webhook-Signature') ?? '';

  const expected = crypto
    .createHmac('sha256', process.env.ASTRATVA_WEBHOOK_SECRET)
    .update(`${timestamp}.${id}.${req.body.toString('utf8')}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  const fresh = /^\d+$/.test(timestamp) && Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;

  if (!fresh || a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(400);
  }
  // Deliveries are at least once: skip an id you have already handled.
  res.sendStatus(200);
});

If you rotate a secret, the old one stops working at once and is never shown again.

Events

quota.warning

Once a month, when use passes 80% of the monthly quota.

{
    "id": "3f6c9a2e-5b1d-4e8f-9a7c-2d4b6e8f0a1c",
    "type": "quota.warning",
    "data": {
        "used": 8000,
        "limit": 10000,
        "resets_at": "2026-12-01T00:00:00Z"
    }
}

quota.exhausted

Once a month, when the quota is used up. Further calls are answered 429 until it resets.

{
    "id": "3f6c9a2e-5b1d-4e8f-9a7c-2d4b6e8f0a1c",
    "type": "quota.exhausted",
    "data": {
        "used": 10000,
        "limit": 10000,
        "resets_at": "2026-12-01T00:00:00Z"
    }
}

key.revoked

An API key was revoked. Calls with it fail from the next request.

{
    "id": "3f6c9a2e-5b1d-4e8f-9a7c-2d4b6e8f0a1c",
    "type": "key.revoked",
    "data": {
        "key_id": "01JC8Z6Q4M3T7V2X9K5N1R8B6D",
        "name": "Production"
    }
}

subscription.ended

The API plan has ended, so the keys stop working. plan is api-starter or api-pro.

{
    "id": "3f6c9a2e-5b1d-4e8f-9a7c-2d4b6e8f0a1c",
    "type": "subscription.ended",
    "data": {
        "plan": "api-starter",
        "ended_at": "2026-12-01T00:00:00Z"
    }
}

horoscope.published

The daily horoscopes for a date are ready. The payload lists the date, signs and languages, not the text.

{
    "id": "3f6c9a2e-5b1d-4e8f-9a7c-2d4b6e8f0a1c",
    "type": "horoscope.published",
    "data": {
        "date": "2026-11-13",
        "signs": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11,
            12
        ],
        "languages": [
            "en",
            "hi",
            "ta",
            "te"
        ]
    }
}

webhook.test

Sent by the "Send test event" button on your developer page, to that endpoint only. You do not subscribe to it: any enabled endpoint can be sent one. hook_id is the endpoint.

{
    "id": "3f6c9a2e-5b1d-4e8f-9a7c-2d4b6e8f0a1c",
    "type": "webhook.test",
    "data": {
        "hook_id": "9b2f4c1e-8d0a-4f53-a6c2-1e7d3b5a9f80",
        "message": "This is a test event."
    }
}