PayPal Webhooks

Create PayPal Webhook

Endpoint

• Method: POST
• URL: /v1/coach/coach-payout/create-paypal-webhook

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer token	Yes

Request Body

Parameter	Type	Description	Required	Validation Rules
url	string	Webhook URL	Yes	required, url
events	array	List of event types to subscribe to	Yes	required, array

Success Response

{
    "success": true,
    "message": "تم إنشاء webhook بنجاح",
    "data": {
        "id": "WH-123456789",
        "url": "https://example.com/webhook",
        "event_types": [
            "PAYMENT.CAPTURE.COMPLETED",
            "PAYMENT.CAPTURE.REFUNDED"
        ],
        "status": "ACTIVE"
    },
    "statusCode": 201
}

Receive PayPal Webhook

Endpoint

• Method: POST
• URL: /v1/coach/paypal-webhooks/receive-paypal-webhook

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
PayPal-Auth-Algo	SHA256withRSA	Yes
PayPal-Cert-Url	PayPal certificate URL	Yes
PayPal-Transmission-Id	Unique transmission ID	Yes
PayPal-Transmission-Sig	PayPal signature	Yes
PayPal-Transmission-Time	Timestamp	Yes

Request Body

{
    "id": "WH-123456789",
    "event_type": "PAYMENT.CAPTURE.COMPLETED",
    "resource": {
        "id": "CAP-123456789",
        "status": "COMPLETED",
        "amount": {
            "currency_code": "USD",
            "value": "100.00"
        },
        "seller_receivable_breakdown": {
            "gross_amount": {
                "currency_code": "USD",
                "value": "100.00"
            },
            "paypal_fee": {
                "currency_code": "USD",
                "value": "3.00"
            },
            "net_amount": {
                "currency_code": "USD",
                "value": "97.00"
            }
        }
    },
    "create_time": "2024-03-20T10:00:00Z"
}

Success Response

{
    "success": true,
    "message": "تم استلام webhook بنجاح",
    "data": [],
    "statusCode": 200
}

Error Responses

Invalid Signature (400)

{
    "success": false,
    "message": "توقيع غير صالح",
    "data": [],
    "statusCode": 400
}

Invalid Event Type (400)

{
    "success": false,
    "message": "نوع الحدث غير مدعوم",
    "data": [],
    "statusCode": 400
}

Important Notes

• PayPal webhooks are used to receive real-time notifications about payment events
• The create webhook endpoint requires authentication
• The receive webhook endpoint requires PayPal-specific headers for verification
• Webhook URLs must be publicly accessible
• Event types must be valid PayPal webhook events
• Webhook signatures are verified for security
• Payment events are processed asynchronously
• Webhook responses should be acknowledged within 20 seconds
• Failed webhook deliveries are retried according to PayPal's retry policy
• Webhook events are logged for auditing purposes
• The system supports multiple webhook URLs for redundancy
• Webhook configurations can be managed through the PayPal dashboard
• Rate limiting may apply to webhook deliveries
• SSL/TLS is required for webhook URLs
• Webhook payloads are encrypted in transit
• Event processing should be idempotent to handle duplicate deliveries