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.
Note: If you would like to handle webhooks through the API, review the reference here
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 property type
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:
{
"type" : "charge.succeeded",
"event_date" : "2013-11-22T15:09:38-06:00",
"transaction" : {
"amount" : 2000.0,
"authorization" : "801585",
"method" : "card",
"operation_type" : "in",
"transaction_type" : "charge",
"card" : {
"type" : "debit",
"brand" : "mastercard",
"address" : {
"line1" : "Calle #1 Interior #2",
"line2" : null,
"line3" : null,
"state" : "Queretaro",
"city" : "Queretaro",
"postal_code" : "76040",
"country_code" : "MX"
},
"card_number" : "1881",
"holder_name" : "Card Holder",
"expiration_month" : "10",
"expiration_year" : "14",
"allows_charges" : true,
"allows_payouts" : true,
"creation_date" : "2013-11-22T15:09:32-06:00",
"bank_name" : "BBVA BANCOMER",
"bank_code" : "012"
},
"status" : "completed",
"id" : "tlxcm4vprtz74qoenuay",
"creation_date" : "2013-11-22T15:09:33-06:00",
"description" : "Description",
"error_message" : null,
"order_id" : "oid_14235"
}
}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
Type
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.
Sign up
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:
{
"type" : "verification",
"event_date" : "2013-11-22T11:04:49-06:00",
"verification_code" : "UY1qqrxw"
}Implementation
To implement your Webhook, you only have to create a Web service with an URL where Openpay can send POST.
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.
