Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur on the Qariyb platform. When an event happens (e.g., a ticket is purchased, an attendee checks in), Qariyb sends a POST request to your configured endpoint with details about the event.

Key Features:

Event-scoped webhooks (each webhook is tied to a specific event)
HMAC-SHA256 payload signing for security
Multiple authentication options
Automatic retries (3 attempts with 60-second delays)
Delivery logging and monitoring

Creating a webhook

Webhooks are created through the Qariyb organizer dashboard:

Navigate to Dashboard → Developer → Webhooks
Click Create Webhook
Configure the webhook settings

Configuration fields

Name
Name
Type
string
Description
A friendly name for your webhook (e.g., "CRM Integration").
Name
Endpoint URL
Type
string
Description
Your HTTPS endpoint that will receive webhook payloads.
Name
Event
Type
string
Description
The Qariyb event this webhook is scoped to.
Name
Description
Type
string
Description
Optional notes about the webhook's purpose.
Name
Signing Secret
Type
string
Description
Secret key for HMAC-SHA256 signature verification (min 16 chars).
Name
Authentication Type
Type
string
Description
How to authenticate requests to your endpoint.
Name
Event Types
Type
string[]
Description
Which webhook events should trigger notifications.

Authentication types

Name
None
Description
No additional authentication headers.
Name
Bearer Token
Description
Adds Authorization: Bearer {your-token} header.
Name
Custom Header
Description
Adds a custom header with your specified name and value.

Example configuration

{
  "name": "Order Notifications",
  "url": "https://api.yourapp.com/webhooks/qariyb",
  "event": "Annual Iftar Dinner 2024",
  "auth_type": "bearer",
  "auth_value": "your-endpoint-bearer-token",
  "events": [
    "order.created",
    "order.completed",
    "payment.received"
  ]
}

Authentication & security

Signing secret

When you provide a signing secret, Qariyb signs each webhook payload using HMAC-SHA256. This allows you to verify that the request genuinely came from Qariyb.

The signature is included in the Signature header:

Signature: 5d41402abc4b2a76b9719d911017c592...

Request headers

Every webhook request includes these headers:

Name
Content-Type
Description
application/json
Name
X-Webhook-Event
Description
The event type (e.g., order.created).
Name
Signature
Description
HMAC-SHA256 signature (if signing secret configured).
Name
Authorization
Description
Bearer token (if Bearer auth configured).

Verifying webhook signatures

Always verify webhook signatures in production to ensure the payload wasn't tampered with and originated from Qariyb.

Verification steps

Get the raw request body
Get the Signature header value
Compute HMAC-SHA256 of the body using your signing secret
Compare signatures using constant-time comparison

Signature Verification

<?php

function verifyWebhookSignature(
    string $payload,
    string $signature,
    string $secret
): bool {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signature);
}

// In your webhook handler:
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SIGNATURE'] ?? '';
$secret = 'your-signing-secret';

if (!verifyWebhookSignature($payload, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Process the webhook...

Payload structure

All webhook payloads follow the Standard Webhooks specification.

Envelope fields

Name
id
Type
string
Description
Unique event identifier (format: evt_{ULID}).
Name
type
Type
string
Description
The event type (e.g., order.created).
Name
timestamp
Type
string
Description
ISO 8601 timestamp when the event occurred.
Name
data
Type
object
Description
The event payload containing entity data.

Data object types

The data object contains an object field indicating the entity type:

Name
event
Description
Event entity (the Qariyb event, not the webhook event).
Name
order
Description
Order entity.
Name
ticket
Description
Ticket entity.
Name
attendee
Description
Attendee/participant entity.
Name
payment
Description
Payment transaction entity.
Name
payout
Description
Payout entity.

Envelope structure

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "order.created",
  "timestamp": "2024-03-15T14:30:00+00:00",
  "data": {
    "object": "order",
    // ... entity-specific fields
  }
}

Event lifecycle

Events related to the lifecycle of your Qariyb events.

event.created

Triggered when a new event is created.

Data fields

Name
object
Type
string
Description
Always event.
Name
id
Type
string
Description
Unique event identifier.
Name
title
Type
string
Description
Event title.
Name
slug
Type
string
Description
URL-friendly event slug.
Name
state
Type
string
Description
Event state (draft, preview, published, etc.).
Name
organization
Type
object
Description
Organization details (id, name, slug).
Name
created_by
Type
object
Description
User who created the event (id, name, email).

event.created payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "event.created",
  "timestamp": "2024-03-15T10:00:00+00:00",
  "data": {
    "object": "event",
    "id": "01JJ7ABCD1234EFGH5678IJKL",
    "title": "Annual Iftar Dinner 2024",
    "slug": "annual-iftar-dinner-2024",
    "state": "draft",
    "ownership_type": "Organization",
    "created_at": "2024-03-15T10:00:00+00:00",
    "organization": {
      "id": "01JJ7MNOP1234QRST5678UVWX",
      "name": "Islamic Community Center",
      "slug": "islamic-community-center"
    },
    "created_by": {
      "id": "01JJ7USER1234ABCD5678EFGH",
      "name": "Ahmed Khan",
      "email": "ahmed@example.com"
    }
  }
}

event.updated

Triggered when event details are modified.

Data fields

Name
object
Type
string
Description
Always event.
Name
id
Type
string
Description
Unique event identifier.
Name
title
Type
string
Description
Updated event title.
Name
updated_fields
Type
string[]
Description
List of fields that were modified.
Name
start_date
Type
string
Description
Event start date (YYYY-MM-DD).
Name
location
Type
object
Description
Location details (type, address, city, country).

event.updated payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "event.updated",
  "timestamp": "2024-03-16T14:30:00+00:00",
  "data": {
    "object": "event",
    "id": "01JJ7ABCD1234EFGH5678IJKL",
    "title": "Annual Iftar Dinner 2024 - Updated",
    "description": "Join us for a beautiful evening...",
    "updated_fields": ["title", "description"],
    "start_date": "2024-03-25",
    "end_date": "2024-03-25",
    "start_time": "18:30",
    "end_time": "22:00",
    "location": {
      "type": "physical",
      "address": "123 Mosque Road",
      "city": "London",
      "country": "United Kingdom",
      "postal_code": "E1 4NS"
    }
  }
}

event.published

Triggered when an event is published and open for registration.

Data fields

Name
object
Type
string
Description
Always event.
Name
id
Type
string
Description
Unique event identifier.
Name
status
Type
string
Description
Always published.
Name
published_at
Type
string
Description
ISO 8601 timestamp of publication.
Name
registration_url
Type
string
Description
Public URL for registration.
Name
ticket_types
Type
array
Description
Available ticket types with pricing and availability.

event.published payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "event.published",
  "timestamp": "2024-03-17T09:00:00+00:00",
  "data": {
    "object": "event",
    "id": "01JJ7ABCD1234EFGH5678IJKL",
    "title": "Annual Iftar Dinner 2024",
    "status": "published",
    "published_at": "2024-03-17T09:00:00+00:00",
    "registration_url": "https://qariyb.com/events/annual-iftar-dinner-2024",
    "ticket_types": [
      {
        "id": "01JJ7TICK1234ABCD5678TYPE",
        "name": "General Admission",
        "price": {
          "amount": 2500,
          "currency": "GBP"
        },
        "quantity": 200,
        "available": 200
      },
      {
        "id": "01JJ7TICK5678EFGH9012TYPE",
        "name": "VIP Table",
        "price": {
          "amount": 10000,
          "currency": "GBP"
        },
        "quantity": 20,
        "available": 20
      }
    ]
  }
}

event.cancelled

Triggered when an event is cancelled.

Data fields

Name
object
Type
string
Description
Always event.
Name
id
Type
string
Description
Unique event identifier.
Name
status
Type
string
Description
Always cancelled.
Name
cancelled_at
Type
string
Description
ISO 8601 timestamp of cancellation.
Name
cancellation_reason
Type
string
Description
Reason for cancellation.
Name
registrations_count
Type
integer
Description
Number of affected registrations.
Name
refunds_initiated
Type
boolean
Description
Whether refunds have been initiated.

event.cancelled payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "event.cancelled",
  "timestamp": "2024-03-20T16:00:00+00:00",
  "data": {
    "object": "event",
    "id": "01JJ7ABCD1234EFGH5678IJKL",
    "title": "Annual Iftar Dinner 2024",
    "status": "cancelled",
    "cancelled_at": "2024-03-20T16:00:00+00:00",
    "cancellation_reason": "Venue unavailable due to unforeseen circumstances",
    "registrations_count": 145,
    "refunds_initiated": true
  }
}

event.completed

Triggered when an event has concluded.

Data fields

Name
object
Type
string
Description
Always event.
Name
id
Type
string
Description
Unique event identifier.
Name
state
Type
string
Description
Always completed.
Name
completed_at
Type
string
Description
ISO 8601 timestamp of completion.
Name
statistics
Type
object
Description
Event statistics (tickets sold, revenue, check-ins).

event.completed payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "event.completed",
  "timestamp": "2024-03-26T00:00:00+00:00",
  "data": {
    "object": "event",
    "id": "01JJ7ABCD1234EFGH5678IJKL",
    "title": "Annual Iftar Dinner 2024",
    "state": "completed",
    "completed_at": "2024-03-26T00:00:00+00:00",
    "start_date": "2024-03-25T18:30:00+00:00",
    "end_date": "2024-03-25T22:00:00+00:00",
    "statistics": {
      "total_tickets_sold": 180,
      "total_revenue": 52500,
      "total_attendees": 180,
      "total_checked_in": 165
    }
  }
}

Orders & tickets

Events related to orders and ticket management.

order.created

Triggered when a new order is initiated (before payment).

Data fields

Name
object
Type
string
Description
Always order.
Name
id
Type
string
Description
Unique order identifier.
Name
order_number
Type
string
Description
Human-readable order number.
Name
status
Type
string
Description
Order status (pending).
Name
items
Type
array
Description
Line items with ticket types and quantities.
Name
total_amount
Type
integer
Description
Total amount in smallest currency unit.
Name
currency
Type
string
Description
ISO 4217 currency code.
Name
buyer
Type
object
Description
Buyer details (id, name, email).

order.created payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "order.created",
  "timestamp": "2024-03-20T19:15:00+00:00",
  "data": {
    "object": "order",
    "id": "01JJ8ORDR1234ABCD5678EFGH",
    "order_number": "QRB-20240320-001234",
    "status": "pending",
    "event": {
      "id": "01JJ7ABCD1234EFGH5678IJKL",
      "title": "Annual Iftar Dinner 2024"
    },
    "items": [
      {
        "ticket_type": "General Admission",
        "quantity": 2,
        "unit_price": 2500,
        "total": 5000
      },
      {
        "ticket_type": "Child Ticket",
        "quantity": 1,
        "unit_price": 1000,
        "total": 1000
      }
    ],
    "sub_total": 6000,
    "tax": 0,
    "fees": 180,
    "total_amount": 6180,
    "currency": "GBP",
    "buyer": {
      "id": "01JJ7USER1234ABCD5678EFGH",
      "name": "Fatima Hassan",
      "email": "fatima@example.com"
    }
  }
}

order.completed

Triggered when payment is successful and order is finalized.

Data fields

Name
object
Type
string
Description
Always order.
Name
id
Type
string
Description
Unique order identifier.
Name
order_number
Type
string
Description
Human-readable order number.
Name
status
Type
string
Description
Order status (completed).
Name
completed_at
Type
string
Description
ISO 8601 timestamp of completion.
Name
payment_method
Type
string
Description
Payment method used (e.g., card).
Name
tickets
Type
array
Description
Generated tickets with IDs and QR codes.

order.completed payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "order.completed",
  "timestamp": "2024-03-20T19:16:30+00:00",
  "data": {
    "object": "order",
    "id": "01JJ8ORDR1234ABCD5678EFGH",
    "order_number": "QRB-20240320-001234",
    "status": "completed",
    "completed_at": "2024-03-20T19:16:30+00:00",
    "payment_method": "card",
    "tickets_generated": 3,
    "total_amount": 6180,
    "currency": "GBP",
    "tickets": [
      {
        "id": "01JJ8TICK1234AAAA5678BBBB",
        "ticket_number": "TKT-001234-001",
        "status": "active",
        "qr_code_url": "https://qariyb.com/storage/qr/TKT-001234-001.png"
      },
      {
        "id": "01JJ8TICK1234CCCC5678DDDD",
        "ticket_number": "TKT-001234-002",
        "status": "active",
        "qr_code_url": "https://qariyb.com/storage/qr/TKT-001234-002.png"
      },
      {
        "id": "01JJ8TICK1234EEEE5678FFFF",
        "ticket_number": "TKT-001234-003",
        "status": "active",
        "qr_code_url": "https://qariyb.com/storage/qr/TKT-001234-003.png"
      }
    ]
  }
}

order.cancelled

Triggered when an order is cancelled.

Data fields

Name
object
Type
string
Description
Always order.
Name
id
Type
string
Description
Unique order identifier.
Name
status
Type
string
Description
Order status (cancelled).
Name
cancelled_at
Type
string
Description
ISO 8601 timestamp of cancellation.
Name
cancellation_reason
Type
string
Description
Reason for cancellation.
Name
tickets_count
Type
integer
Description
Number of tickets that were cancelled.

order.cancelled payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "order.cancelled",
  "timestamp": "2024-03-21T10:00:00+00:00",
  "data": {
    "object": "order",
    "id": "01JJ8ORDR1234ABCD5678EFGH",
    "order_number": "QRB-20240320-001234",
    "total_amount": 6180,
    "currency": "GBP",
    "status": "cancelled",
    "cancelled_at": "2024-03-21T10:00:00+00:00",
    "cancellation_reason": "Customer requested cancellation",
    "tickets_count": 3,
    "event": {
      "id": "01JJ7ABCD1234EFGH5678IJKL",
      "title": "Annual Iftar Dinner 2024"
    },
    "buyer": {
      "id": "01JJ7USER1234ABCD5678EFGH",
      "name": "Fatima Hassan",
      "email": "fatima@example.com"
    }
  }
}

order.refunded

Triggered when an order is refunded.

Data fields

Name
object
Type
string
Description
Always order.
Name
id
Type
string
Description
Unique order identifier.
Name
status
Type
string
Description
Order status (refunded).
Name
refunded_at
Type
string
Description
ISO 8601 timestamp of refund.
Name
refund
Type
object
Description
Refund details (amount, currency, reason, provider ID).

order.refunded payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "order.refunded",
  "timestamp": "2024-03-21T11:30:00+00:00",
  "data": {
    "object": "order",
    "id": "01JJ8ORDR1234ABCD5678EFGH",
    "order_number": "QRB-20240320-001234",
    "status": "refunded",
    "refunded_at": "2024-03-21T11:30:00+00:00",
    "refund": {
      "amount": 6180,
      "currency": "GBP",
      "reason": "Event cancelled",
      "provider_refund_id": "re_3OxYZ1234567890"
    }
  }
}

ticket.issued

Triggered when a ticket is generated after successful payment.

Data fields

Name
object
Type
string
Description
Always ticket.
Name
id
Type
string
Description
Unique ticket identifier.
Name
ticket_number
Type
string
Description
Human-readable ticket number.
Name
status
Type
string
Description
Ticket status (active).
Name
event
Type
object
Description
Event details (id, title, start_date, venue).
Name
ticket_type
Type
object
Description
Ticket type (name, price).
Name
qr_code_url
Type
string
Description
URL to ticket QR code image.

ticket.issued payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "ticket.issued",
  "timestamp": "2024-03-20T19:16:30+00:00",
  "data": {
    "object": "ticket",
    "id": "01JJ8TICK1234AAAA5678BBBB",
    "ticket_number": "TKT-001234-001",
    "status": "active",
    "event": {
      "id": "01JJ7ABCD1234EFGH5678IJKL",
      "title": "Annual Iftar Dinner 2024",
      "start_date": "2024-03-25",
      "venue": "Islamic Community Center"
    },
    "ticket_type": {
      "name": "General Admission",
      "price": 2500
    },
    "order": {
      "id": "01JJ8ORDR1234ABCD5678EFGH",
      "order_number": "QRB-20240320-001234"
    },
    "holder": null,
    "qr_code_url": "https://qariyb.com/storage/qr/TKT-001234-001.png"
  }
}

ticket.checked_in

Triggered when a ticket is scanned/checked in at the event.

Data fields

Name
object
Type
string
Description
Always ticket.
Name
id
Type
string
Description
Unique ticket identifier.
Name
ticket_number
Type
string
Description
Human-readable ticket number.
Name
checked_in_at
Type
string
Description
ISO 8601 timestamp of check-in.
Name
check_in
Type
object
Description
Check-in details (gate, device, staff member).
Name
attendee
Type
object
Description
Attendee details (name, email).

ticket.checked_in payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "ticket.checked_in",
  "timestamp": "2024-03-25T18:45:00+00:00",
  "data": {
    "object": "ticket",
    "id": "01JJ8TICK1234AAAA5678BBBB",
    "ticket_number": "TKT-001234-001",
    "checked_in_at": "2024-03-25T18:45:00+00:00",
    "check_in": {
      "gate": "main",
      "device": "iPhone",
      "checked_in_by": {
        "id": "01JJ7STAFF1234ABCD5678EF",
        "name": "Omar Ali"
      },
      "prayer_session": null
    },
    "attendee": {
      "name": "Fatima Hassan",
      "email": "fatima@example.com"
    }
  }
}

Attendees

Events related to attendee registration and management.

attendee.registered

Triggered when a new attendee registration is completed.

Data fields

Name
object
Type
string
Description
Always attendee.
Name
participant_id
Type
string
Description
Unique participant identifier.
Name
ticket_id
Type
string
Description
Associated ticket identifier.
Name
ticket_number
Type
string
Description
Human-readable ticket number.
Name
registration_type
Type
string
Description
Registration type (paid, free, rsvp).
Name
registered_at
Type
string
Description
ISO 8601 timestamp of registration.

attendee.registered payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "attendee.registered",
  "timestamp": "2024-03-20T19:16:30+00:00",
  "data": {
    "object": "attendee",
    "participant_id": "01JJ8PART1234ABCD5678EFGH",
    "ticket_id": "01JJ8TICK1234AAAA5678BBBB",
    "ticket_number": "TKT-001234-001",
    "event": {
      "id": "01JJ7ABCD1234EFGH5678IJKL",
      "title": "Annual Iftar Dinner 2024"
    },
    "registration_type": "paid",
    "ticket_type": "General Admission",
    "registered_at": "2024-03-20T19:16:30+00:00"
  }
}

attendee.cancelled

Triggered when an attendee's registration is cancelled.

Data fields

Name
object
Type
string
Description
Always attendee.
Name
id
Type
string
Description
Unique attendee identifier.
Name
ticket_number
Type
string
Description
Human-readable ticket number.
Name
name
Type
string
Description
Attendee name.
Name
email
Type
string
Description
Attendee email.
Name
cancelled_at
Type
string
Description
ISO 8601 timestamp of cancellation.
Name
cancellation_reason
Type
string
Description
Reason for cancellation.

attendee.cancelled payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "attendee.cancelled",
  "timestamp": "2024-03-21T10:00:00+00:00",
  "data": {
    "object": "attendee",
    "id": "01JJ8TICK1234AAAA5678BBBB",
    "ticket_number": "TKT-001234-001",
    "name": "Fatima Hassan",
    "email": "fatima@example.com",
    "ticket_type": "General Admission",
    "cancelled_at": "2024-03-21T10:00:00+00:00",
    "cancellation_reason": "Customer requested cancellation",
    "event": {
      "id": "01JJ7ABCD1234EFGH5678IJKL",
      "title": "Annual Iftar Dinner 2024"
    },
    "order": {
      "id": "01JJ8ORDR1234ABCD5678EFGH",
      "order_number": "QRB-20240320-001234"
    }
  }
}

attendee.checked_in

Triggered when an attendee checks in at the event.

Data fields

Name
object
Type
string
Description
Always attendee.
Name
participant_id
Type
string
Description
Unique participant identifier.
Name
name
Type
string
Description
Attendee name.
Name
email
Type
string
Description
Attendee email.
Name
ticket_number
Type
string
Description
Human-readable ticket number.
Name
checked_in_at
Type
string
Description
ISO 8601 timestamp of check-in.
Name
check_in_gate
Type
string
Description
Gate where check-in occurred.

attendee.checked_in payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "attendee.checked_in",
  "timestamp": "2024-03-25T18:45:00+00:00",
  "data": {
    "object": "attendee",
    "participant_id": "01JJ8PART1234ABCD5678EFGH",
    "name": "Fatima Hassan",
    "email": "fatima@example.com",
    "ticket_number": "TKT-001234-001",
    "checked_in_at": "2024-03-25T18:45:00+00:00",
    "check_in_gate": "main",
    "event": {
      "id": "01JJ7ABCD1234EFGH5678IJKL",
      "title": "Annual Iftar Dinner 2024"
    }
  }
}

Payments

Events related to payment processing and payouts.

payment.received

Triggered when a payment is successfully processed.

Data fields

Name
object
Type
string
Description
Always payment.
Name
id
Type
string
Description
Unique payment identifier.
Name
provider_transaction_id
Type
string
Description
Payment provider's transaction ID.
Name
amount
Type
integer
Description
Payment amount in smallest currency unit.
Name
currency
Type
string
Description
ISO 4217 currency code.
Name
status
Type
string
Description
Payment status (completed).
Name
provider
Type
string
Description
Payment provider (e.g., stripe).
Name
fees
Type
object
Description
Fee breakdown (platform_fee, provider_fee, net_amount).

payment.received payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "payment.received",
  "timestamp": "2024-03-20T19:16:25+00:00",
  "data": {
    "object": "payment",
    "id": "01JJ8ORDR1234ABCD5678EFGH",
    "provider_transaction_id": "pi_3OxYZ1234567890abcdef",
    "amount": 6180,
    "currency": "GBP",
    "status": "completed",
    "provider": "stripe",
    "payment_method": "card",
    "order": {
      "id": "01JJ8ORDR1234ABCD5678EFGH",
      "order_number": "QRB-20240320-001234"
    },
    "fees": {
      "platform_fee": 185,
      "provider_fee": 149,
      "net_amount": 5846
    }
  }
}

payment.failed

Triggered when a payment attempt fails.

Data fields

Name
object
Type
string
Description
Always payment.
Name
provider_transaction_id
Type
string
Description
Payment provider's transaction ID.
Name
amount
Type
integer
Description
Attempted payment amount.
Name
currency
Type
string
Description
ISO 4217 currency code.
Name
status
Type
string
Description
Payment status (failed).
Name
failure_reason
Type
string
Description
Machine-readable failure code.
Name
failure_message
Type
string
Description
Human-readable failure message.

payment.failed payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "payment.failed",
  "timestamp": "2024-03-20T19:16:25+00:00",
  "data": {
    "object": "payment",
    "provider_transaction_id": "pi_3OxYZ1234567890failed",
    "amount": 6180,
    "currency": "GBP",
    "status": "failed",
    "failure_reason": "card_declined",
    "failure_message": "Your card was declined. Please try a different payment method.",
    "order": {
      "id": "01JJ8ORDR1234ABCD5678EFGH",
      "order_number": "QRB-20240320-001234"
    }
  }
}

payout.initiated

Triggered when a payout to the organizer is initiated.

Data fields

Name
object
Type
string
Description
Always payout.
Name
id
Type
string
Description
Unique payout identifier.
Name
provider_payout_id
Type
string
Description
Payment provider's payout ID.
Name
amount
Type
integer
Description
Payout amount in smallest currency unit.
Name
currency
Type
string
Description
ISO 4217 currency code.
Name
status
Type
string
Description
Payout status (pending).
Name
type
Type
string
Description
Payout type (e.g., event_settlement).
Name
estimated_arrival
Type
string
Description
Estimated arrival date.

payout.initiated payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "payout.initiated",
  "timestamp": "2024-03-27T09:00:00+00:00",
  "data": {
    "object": "payout",
    "id": "01JJ9PAYO1234ABCD5678EFGH",
    "provider_payout_id": "po_3OxYZ1234567890payout",
    "amount": 485000,
    "currency": "GBP",
    "status": "pending",
    "type": "event_settlement",
    "event": {
      "id": "01JJ7ABCD1234EFGH5678IJKL",
      "title": "Annual Iftar Dinner 2024"
    },
    "payment_account": {
      "id": "01JJ7ACCT1234ABCD5678EFGH",
      "provider_account_id": "acct_1234567890"
    },
    "estimated_arrival": "2024-03-29T00:00:00+00:00"
  }
}

payout.completed

Triggered when a payout has been successfully deposited.

Data fields

Name
object
Type
string
Description
Always payout.
Name
id
Type
string
Description
Unique payout identifier.
Name
provider_payout_id
Type
string
Description
Payment provider's payout ID.
Name
amount
Type
integer
Description
Payout amount in smallest currency unit.
Name
currency
Type
string
Description
ISO 4217 currency code.
Name
status
Type
string
Description
Payout status (paid).
Name
paid_at
Type
string
Description
ISO 8601 timestamp when deposited.
Name
bank_account
Type
object
Description
Bank account details (last4, bank_name).

payout.completed payload

{
  "id": "evt_01JJ8K3M5N7P9Q2R4S6T8V0X",
  "type": "payout.completed",
  "timestamp": "2024-03-29T06:00:00+00:00",
  "data": {
    "object": "payout",
    "id": "01JJ9PAYO1234ABCD5678EFGH",
    "provider_payout_id": "po_3OxYZ1234567890payout",
    "amount": 485000,
    "currency": "GBP",
    "status": "paid",
    "paid_at": "2024-03-29T06:00:00+00:00",
    "bank_account": {
      "last4": "****",
      "bank_name": "Unknown"
    }
  }
}

Best practices

Respond quickly

Return a 2xx status code within 30 seconds. If processing takes longer, acknowledge receipt immediately and process asynchronously.

Handle retries gracefully

Qariyb retries failed webhooks up to 3 times with 60-second delays. Implement idempotency using the id field to avoid duplicate processing.

Verify signatures

Always verify webhook signatures in production to ensure payloads are authentic and untampered.

Use HTTPS

Webhook URLs must use HTTPS. This is enforced by Qariyb and ensures data is encrypted in transit.

Handle missing data

Not all fields are guaranteed. Always check for existence before accessing nested properties.

Monitor delivery status

Use the Qariyb dashboard at Dashboard → Developer → Webhooks → Logs to monitor deliveries, view response times, and re-send failed webhooks.

Best Practices

<?php

// 1. Acknowledge immediately, process later
http_response_code(200);
echo json_encode(['received' => true]);

// Flush output before processing
if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

// 2. Idempotency check
$eventId = $payload['id'];
if (webhookAlreadyProcessed($eventId)) {
    exit; // Already handled
}

// 3. Process and record
processWebhook($payload);
markWebhookProcessed($eventId);

Technical details

Retry policy

Name
Max Retries
Description
3 attempts
Name
Retry Delay
Description
60 seconds between attempts
Name
Timeout
Description
30 seconds per request

Event type reference

Category	Event Type	Description
Events	`event.created`	New event created
	`event.updated`	Event details modified
	`event.published`	Event published for registration
	`event.cancelled`	Event cancelled
	`event.completed`	Event concluded
Orders	`order.created`	New order initiated
	`order.completed`	Order payment successful
	`order.cancelled`	Order cancelled
	`order.refunded`	Order refunded
Tickets	`ticket.issued`	Ticket generated
	`ticket.checked_in`	Ticket scanned at event
Attendees	`attendee.registered`	New registration completed
	`attendee.cancelled`	Registration cancelled
	`attendee.checked_in`	Attendee checked in
Payments	`payment.received`	Payment successful
	`payment.failed`	Payment failed
	`payout.initiated`	Payout started
	`payout.completed`	Payout deposited

Learn about API authentication