Notifications
What is a Webhook?
The WebHooks let you receive notifications in the web service configured in your account about all the transactions made. For example, this allows you to know when a charge was made to a card or when a deposit has been successful.
Nota: If you would like to handle webhooks through the API, review the reference [here][webhook-reference]
Webhook Object
Every time a transaction is made, Openpay will send the registered URLs through a JSON object to receive WebHooks. Openpay can add more fields in the future, or add new values to existing fields, so it is recommended that your Webhook can handle unknown additional data.
Parameters
The webhook object contains the following information:
Field | Description |
---|---|
type | string The type of the event that generated the notification. |
event_date | timestamp Creation date of the event in ISO8601 format. |
transaction | string The transaction object related to the event. This is not send in verification type notifications. |
verification_code | string The Webhook verification code. This is send only in verification type notifications. |
All transactions notifications will be send to the URLs you have registered. To distinguish a transaction, use the type
property.
Note: Openpay will attempt to deliver the notification until it gets a success response. This can cause some notifications are sent twice, so you should be prepared to receive the same notification more than once.
Example:
Valid Webhook service features
Endpoint: Domains only (No IPs). example: https://notifications.merchant.com
Port: 443/TCP, 1518/TCP, 1519/TCP, 8443/TCP y 10443/TCP
Protocol: HTTPS/TLS_1.2
Certificate: Valid (Signed by public CA and match with domain).
Types
Tipe | Description |
---|---|
verification | The notifications contains the Webhook verification code. |
charge.created | A charge that has to be paid through a bank transfer was created. |
charge.succeeded | It means that the charge was completed (via card, bank or store). |
charge.refunded | A card charge was reimbursed. |
payout.created | A payment was scheduled. |
payout.succeeded | A payment was sent. |
payout.failed | The payment was rejected. |
transfer.succeeded | A transfer between customer was made. |
fee.succeeded | The customer was charged with a fee. |
spei.received | The account received funds through SPEI. |
chargeback.created | A chargeback of a card charge was received. |
chargeback.rejected | The chargeback is rejected in favor of the business. |
chargeback.accepted | The chargeback is accepted. A new chargeback transaction is created and will deduct the funds from your account. |
Your server must be prepared to accept unknown types notifications, to ensure compatibility with future versions.
Configuration
To configure a Webhook follow these steps:
Login to Openpay Dashboard using your email and password
Simply click on your name to view your business profile.
In WebHooks section, select the option: Add + Webhook
In the form shown, specify the complete URL of your webhook, including the protocol used. It is recommended to use https.
If your Webhook requires HTTP authentication, set it. Currently only HTTP Basic authentication is supported.
Click on the Save button.
Verification
After the webhook configuration, Openpay will send a POST via a JSON message to the specified URL, it will have a object type Webhook notification. Your service must keep the verification code in some way, and return the status 200 OK.
If for some reason you the verification code to be resent, just select the Forward Code option. A new verification code will be generated and sent to the URL provided.
Once you already have the verification code of the Webhook, select the Verify option and enter the code provided in the object of the notification. This will activate the Webhook in Openpay and start receiving notifications of transactions.
Example:
Implementation
To implement your Webhook, you only have to create a Web service with an URL where Openpay can send POST
requests.
Your Webhook should handle different types of notifications, including receiving the verification code, so you can register it in Openpay.
Your Webhook should also be able to receive unexpected types notifications to ensure compatibility with future versions.
The Webhook should return an HTTP 200 OK
status when it receives a notification, otherwise Openpay will retry sending the notification continuously.
Remove
At any time you can select the -Remove option on the dashboard to remove a Webhook and stop receiving notifications to that URL.