Webhooks API

Receive real-time notifications when prayer times are reached. The webhook system monitors prayer times for specified locations and automatically sends HTTP POST requests to your registered webhook URLs with HMAC signature verification for security.

✨ Features

Real-time prayer time notifications
Support for all 6 prayer times (Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha)
Multiple calculation methods (MWL, ISNA, Egypt, UmmAlQura)
Timezone-aware scheduling
HMAC signature verification for security
Customizable metadata support
Test webhook functionality

Create Webhook Subscription

Create a new webhook subscription to receive prayer time notifications.

POST/v1/webhooks

Example Request

curl -X POST "https://api.falakapi.com/v1/webhooks" \
  -H "X-API-Key: fak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "prayer_types": ["fajr", "dhuhr", "asr", "maghrib", "isha"],
    "latitude": 24.7136,
    "longitude": 46.6753,
    "timezone": "Asia/Riyadh",
    "method": "UmmAlQura",
    "metadata": {
      "user_id": "12345",
      "location": "Riyadh"
    }
  }'

Example Response

{
  "subscription": {
    "id": "a1b2c3d4e5f6...",
    "url": "https://your-server.com/webhook",
    "prayer_types": ["fajr", "dhuhr", "asr", "maghrib", "isha"],
    "coordinates": {
      "latitude": 24.7136,
      "longitude": 46.6753
    },
    "timezone": "Asia/Riyadh",
    "method": "UmmAlQura",
    "active": true,
    "created_at": "2025-11-16T10:00:00Z",
    "updated_at": "2025-11-16T10:00:00Z"
  },
  "secret": "your-webhook-secret-key",
  "message": "Webhook created successfully. Save the secret - it won't be shown again!"
}

Notes

•Save the secret key returned in the response - it's only shown once!
•The secret is used to verify webhook signatures for security
•Webhooks trigger within ±2 minutes of the actual prayer time

Request Body Fields

Field	Type	Required	Description
url	string	Required	Your webhook endpoint URL (must be publicly accessible)
prayer_types	array	Required	Array of prayer types: ["fajr", "sunrise", "dhuhr", "asr", "maghrib", "isha"]
latitude	float	Required	Latitude of the location (-90 to 90)
longitude	float	Required	Longitude of the location (-180 to 180)
timezone	string	Optional	IANA timezone (e.g., "Asia/Riyadh"). Auto-detected if not provided.
method	string	Optional	Prayer calculation method (default: "MWL")
metadata	object	Optional	Custom metadata object (included in webhook payload)

Get All Webhooks

Retrieve all your webhook subscriptions.

GET/v1/webhooks

Example Request

curl "https://api.falakapi.com/v1/webhooks" \
  -H "X-API-Key: fak_your_api_key_here"

Example Response

{
  "subscriptions": [
    {
      "id": "a1b2c3d4e5f6...",
      "url": "https://your-server.com/webhook",
      "prayer_types": ["fajr", "maghrib", "isha"],
      "coordinates": {
        "latitude": 24.7136,
        "longitude": 46.6753
      },
      "timezone": "Asia/Riyadh",
      "method": "UmmAlQura",
      "active": true,
      "created_at": "2025-11-16T10:00:00Z",
      "updated_at": "2025-11-16T10:00:00Z"
    }
  ],
  "count": 1
}

Get Single Webhook

Retrieve a specific webhook subscription by ID.

GET/v1/webhooks/:id

Example Request

curl "https://api.falakapi.com/v1/webhooks/a1b2c3d4e5f6" \
  -H "X-API-Key: fak_your_api_key_here"

Example Response

{
  "subscription": {
    "id": "a1b2c3d4e5f6...",
    "url": "https://your-server.com/webhook",
    "prayer_types": ["fajr", "maghrib", "isha"],
    "coordinates": {
      "latitude": 24.7136,
      "longitude": 46.6753
    },
    "timezone": "Asia/Riyadh",
    "method": "UmmAlQura",
    "active": true,
    "created_at": "2025-11-16T10:00:00Z",
    "updated_at": "2025-11-16T10:00:00Z"
  }
}

Update Webhook

Update an existing webhook subscription. All fields are optional.

PUT/v1/webhooks/:id

Example Request

curl -X PUT "https://api.falakapi.com/v1/webhooks/a1b2c3d4e5f6" \
  -H "X-API-Key: fak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-server.com/webhook",
    "prayer_types": ["fajr", "maghrib", "isha"],
    "active": true,
    "metadata": {
      "updated": true
    }
  }'

Example Response

{
  "subscription": {
    "id": "a1b2c3d4e5f6...",
    "url": "https://new-server.com/webhook",
    "prayer_types": ["fajr", "maghrib", "isha"],
    "active": true,
    "updated_at": "2025-11-16T11:00:00Z"
  }
}

Delete Webhook

Delete a webhook subscription.

DELETE/v1/webhooks/:id

Example Request

curl -X DELETE "https://api.falakapi.com/v1/webhooks/a1b2c3d4e5f6" \
  -H "X-API-Key: fak_your_api_key_here"

Example Response

{
  "message": "Webhook deleted successfully"
}

Test Webhook

Manually trigger a test webhook to verify your endpoint is working correctly.

POST/v1/webhooks/:id/test

Example Request

curl -X POST "https://api.falakapi.com/v1/webhooks/a1b2c3d4e5f6/test" \
  -H "X-API-Key: fak_your_api_key_here"

Example Response

{
  "message": "Test webhook triggered successfully"
}

Get Scheduler Statistics

Get statistics about the webhook scheduler system.

GET/v1/webhooks/stats

Example Request

curl "https://api.falakapi.com/v1/webhooks/stats" \
  -H "X-API-Key: fak_your_api_key_here"

Example Response

{
  "stats": {
    "active_subscriptions": 10,
    "total_subscriptions": 12,
    "triggered_today": 45,
    "check_interval": "1m0s",
    "cache_entries": 10
  }
}

Webhook Payload

When a prayer time is reached, the system sends a POST request to your webhook URL with the following payload:

{
  "subscription_id": "a1b2c3d4e5f6...",
  "prayer_type": "fajr",
  "prayer_time": "2025-11-16T05:30:00+03:00",
  "coordinates": {
    "latitude": 24.7136,
    "longitude": 46.6753
  },
  "timezone": "Asia/Riyadh",
  "method": "UmmAlQura",
  "metadata": {
    "user_id": "12345",
    "location": "Riyadh"
  },
  "timestamp": "2025-11-16T05:30:15Z"
}

Webhook Headers

The webhook request includes the following headers:

Content-Type: application/json
User-Agent: FalakAPI-Webhook/1.0
X-Webhook-ID: a1b2c3d4e5f6...
X-Webhook-Signature: <hmac-sha256-signature>

Signature Verification

Always verify the HMAC signature to ensure webhook requests are legitimate and come from FalakAPI. The signature is calculated using HMAC-SHA256 with your webhook secret.

JavaScript/Node.js Example

const crypto = require('crypto');
const express = require('express');

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = 'your-webhook-secret-key';
  
  // Calculate expected signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(req.body);
  const expectedSignature = hmac.digest('hex');
  
  // Verify signature
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Parse and process the webhook
  const payload = JSON.parse(req.body);
  console.log('Prayer time reached:', payload.prayer_type);
  
  res.status(200).send('OK');
});

app.listen(3000);

Python Example

import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    secret = 'your-webhook-secret-key'
    
    # Calculate expected signature
    expected_signature = hmac.new(
        secret.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()
    
    # Verify signature
    if not hmac.compare_digest(signature, expected_signature):
        return 'Invalid signature', 401
    
    # Process the webhook
    payload = request.json
    print(f"Prayer time reached: {payload['prayer_type']}")
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

Prayer Types

Prayer Type	Description
fajr	Dawn prayer
sunrise	Sunrise (not a prayer, but useful for timing)
dhuhr	Noon prayer
asr	Afternoon prayer
maghrib	Sunset prayer
isha	Night prayer

Best Practices

Idempotency: Your webhook endpoint should be idempotent, as webhooks might be retried in case of failures.
Quick Response: Respond to webhook requests quickly (within 30 seconds). If you need heavy processing, acknowledge first and process asynchronously.
Signature Verification: Always verify the webhook signature to ensure requests are legitimate.
Error Handling: Return appropriate HTTP status codes (200-299 for success, 400-499 for client errors, 500-599 for server errors).
Testing: Use the test webhook endpoint to verify your integration before relying on automatic triggers.
Monitoring: Monitor your webhook endpoint to ensure it's receiving and processing requests correctly.

⚠️ Important Notes

Webhooks trigger within ±2 minutes of the actual prayer time
Each prayer is triggered only once per day
The scheduler checks every minute
Your webhook URL must be publicly accessible
Save your webhook secret when creating a subscription - it's only shown once!