Webhooks

AlmondPay webhooks allow your application to receive real-time notifications about specific events occurring in the AlmondPay system. Instead of polling the API for updates, webhooks push event data directly to your configured endpoint.

For example, when a payment is successfully processed, AlmondPay sends a payment.success event to your webhook URL, enabling your application to update the payment status or trigger additional actions like notifying customers or updating logs.

---

Supported Events

Event Name	Description
payment.success	Triggered when a payment is successfully processed.
payment.failed	Triggered when a payment attempt fails.

---

Webhook Request Format

When an event occurs, AlmondPay sends an HTTP POST request to your configured webhook URL. The request includes headers for metadata and a JSON body containing event-specific details.

Request Headers

Header Name	Description
X-Almond-Webhook-Signature	HMAC signature for verifying the request's authenticity.
X-Webhook-Id	Unique identifier for the webhook event.
X-Webhook-Timestamp	Unix timestamp when the event occurred.
Content-Type	The request content type, which is application/json.

Example Request Headers

JSON

{
  "Content-Type": "application/json",
  "X-Almond-Webhook-Signature": "c37ef30967f502fb0f90b9dd7f492783ed24a745e3bdd75569b3cf9ab677d44c",
  "X-Webhook-Id": "event_rzk6k3406l5ct9joo5pj56",
  "X-Webhook-Timestamp": "1731566875"
}

Request Body

Field Name	Type	Description
event	string	The event name (e.g., payment.success).
account_id	string	Unique identifier for the account associated with the event.
payment_id	string	Unique identifier for the payment associated with the event.
payment_details	object	Details about the payment, including a message and additional data.
timestamp	string	ISO 8601 timestamp of when the event occurred.
external_reference (optional)	string	An external reference for the payment, if applicable.
metadata (optional)	object	Additional metadata sent with the event.

Example Request Body

JSON

{
  "event": "payment.success",
  "account_id": "account_24m1hgtui39t86qg2wx4f9",
  "payment_id": "pmt_35oij81vhvk4n6vtbgo7ni",
  "payment_details": {
    "message": "Payment successful",
    "data": {}
  },
  "timestamp": "2024-11-14T06:41:47.000848+00:00",
  "external_reference": "order_12345",
  "metadata": {
    "status": "success",
    "response_code": 200,
    "data": {
      "payment_id": "pmt_yfxkkfi5fwvemfkm222vqd"
    }
  }
}

---

Configuring Webhooks

1. Set Your Webhook URL

   • Log in to the AlmondPay dashboard.
   • Navigate to Settings > Webhooks.
   • Enter your application's webhook URL (e.g., https://your-server.com/webhooks/almondpay).

2. Test Your Endpoint

   • Use the AlmondPay dashboard to send test events to verify your webhook URL.

3. Enable Retry Logic

   • AlmondPay retries failed webhook requests up to 10 times with exponential backoff (5min, 10min, 30min, 1hr, 2hrs, 6hrs, 12hrs, 24hrs, 48hrs).

---

Securing Webhooks

To ensure webhook requests come from AlmondPay, verify the X-Almond-Webhook-Signature using HMAC with your webhook secret key.

Signature Validation Steps:

1. Retrieve the X-Almond-Webhook-Signature from the request headers.
2. Compute an HMAC SHA-256 hash of the request body using your webhook secret.
3. Compare your computed hash with the X-Almond-Webhook-Signature. If they match, the request is authentic.

Example in Python

Python

import hmac
import hashlib

def verify_signature(request_body, signature, secret_key):
    # Compute the HMAC hash
    computed_hash = hmac.new(
        key=secret_key.encode(),
        msg=request_body.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(computed_hash, signature)

---

Responding to Webhooks

AlmondPay expects a 200 OK response from your server within 5 seconds. Failing to respond appropriately will trigger retries.

Example Response for Success

JSON

{
  "status": "success",
  "message": "Webhook processed successfully"
}

---

Error Handling

If an error occurs in your webhook endpoint:

• Return a 4xx or 5xx HTTP status code.
• AlmondPay will retry the request after a delay (up to 10 retries).

---

Example Use Cases

1. Update Database
   Log the payment status in your database using the payment_id and event fields.

2. Notify Customers
   Send an email or SMS to customers when a payment is successful.

3. Trigger Business Logic
   Update your internal systems (e.g., order fulfillment) based on the event data.

---

Testing Webhooks

You can test your webhook integration using tools like:

• Ngrok: For exposing your local server to the internet.
• Postman: For sending sample webhook requests.

---

Common Issues and Solutions

Issue	Cause	Solution
Missing 200 OK response	Webhook endpoint errors or timeouts	Check server logs and ensure quick processing.
Signature validation fails	Incorrect secret key or logic	Verify your HMAC implementation.
Webhook not triggered	Invalid webhook URL in dashboard	Double-check and update the URL.