Webhooks

Webhooks let you subscribe to real-time events from the Ummat platform. When something happens — a new event is published, a donation is completed, prayer times are updated — we send an HTTP POST to your endpoint.

Creating a subscription

Subscriptions are managed from the Developer › Webhooks panel or via the API. Requires the webhook:write scope.

mutation CreateWebhook {
  insert_sa_webhook_subs_one(object: {
    api_key_id: "your-key-id"
    url: "https://yourapp.com/webhooks/ummat"
    event_types: ["event.created", "prayer_times.updated"]
    secret: "your-signing-secret"
  }) {
    id
    url
    event_types
    is_active
  }
}

Verifying signatures

Every delivery includes an X-Ummat-Signature header. Verify it to confirm the request came from Ummat:

import crypto from 'crypto';

function verifySignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

The payload is the raw request body string — do not parse it before verifying.

Delivery envelope

Every webhook POST body has this shape:

{
  "id": "evt_01hzxxxxx",
  "type": "event.created",
  "created_at": "2026-05-03T14:22:00Z",
  "api_version": "2026-05",
  "data": {
    // event-specific payload — see Event Reference
  }
}

Retry policy

If your endpoint returns anything other than a 2xx status, or times out after 30 seconds, we retry with exponential backoff:

After 6 failed attempts the subscription is marked as failing. You can view and replay deliveries from the delivery log.

Best practices

• Respond with 200 immediately. Process the payload asynchronously.
• Always verify the signature before acting on the payload.
• Use the delivery id to deduplicate retried events.
• Set up a delivery log alert if a subscription enters the failing state.