Webhooks play a crucial role in your payment integration with NectaPay, as they allow NectaPay to notify you about various events happening on your account, such as successful payments or failed transactions. A webhook URL acts as an endpoint on your server where you can receive these notifications in the form of POST requests with JSON bodies containing event details.

Webhooks are particularly useful for payments that occur outside your application's control, such as payments received via dynamic or static accounts. By setting up a webhook, you can be informed when such payments are completed, enabling you to take appropriate actions based on the event details.

The structure of all webhook payloads includes the following key components:

response_code: Indicates the status of the transaction (0 for successful)
webhook_event: Describes the type of event
hash_key Your webhook hash key
data: A consistent object containing event details, including:
TransactionId: Transaction ID
AmountPaid: Transaction amount paid
AmountExpected: Expected transaction amount from the customer (constant for static accounts)
SettlementAmountDue: Amount to settle, credited to the customer's wallet account for digital wallets
Charges: Transaction fee
Narration: Transaction description
CustomerId: Payment reference for static accounts or transaction ID for dynamic accounts
MerchantId: Your ID on the NectaPay platform
AccountNumber: Account number initiating the transaction
CreatedAt: Date and time of transaction creation
ResponseCode: Transaction status code
AccountType: Account type (STATIC for static accounts or DYNAMIC for dynamic accounts)
IpAddress: IP address of the transaction source

To enable webhooks on your NectaPay account, you need to:

1. Log in to your dashboard and navigate to Settings.

2. Access the Webhooks section to add your webhook URL.

3. Check all the relevant boxes and save your settings.

When implementing a webhook endpoint on your server, ensure to verify webhook signatures. You can set a secret hash to verify that incoming requests are from NectaPay. This hash is used to encrypt the payload using the hash_hmac function with the sha256 algorithm, and the encrypted payload is stored in the X-Hash header. You can compare this encrypted value with the X-Hash header to ensure the authenticity of the request.

To acknowledge receipt of a webhook, your endpoint should return a 200 HTTP status code. It's important to have a backup strategy in case your webhook endpoint fails, such as setting up a background job to poll for pending transactions at regular intervals.

Lastly, follow best practices such as using a secret hash, re-querying to verify details, responding quickly to requests, and ensuring your event processing is idempotent to prevent processing the same event multiple times.