Webhooks
Overview#
Whenever an event occurs in the InPlayer platform, that is of interest to you as our merchant, we automatically notify you using webhooks. Even more so, you can build or set up applications which are subscribed to certain events on our platform. When these events are triggered, we send HTTP POST requests with specific payloads to the webhooks' configured URL.
Typically, the webhooks are being used for creating or updating a platform action/operation tracker for triggering marketing campaigns, for syncing data between platforms, or for fetching results of backend applications' operations.
You can install a handful of webhooks on your merchant account by setting up a webhook URL and by selecting the specific events you have interest in being notified of. You can find the webhooks’ setup details and other options in the Webhooks Settings section. More precisely, once you navigate to the InPlayer’s dashboard, open the top right-hand corner menu and choose 'Webhooks'.
Payloads#
Each event type has a specific payload format. The InPlayer webhooks’ payload has two main parts: payload headers and payload data.
Payload headers#
The HTTP POST requests sent to your webhook URL have several headers, including the custom InPlayer signature header. You will use this signature to validate the event concerned, as described in the validating events section.
| Header | Value |
|---|---|
| X-InPlayer-Signature | The signature is created by hashing your secret key together with the request payload, using the sha256 algorithm |
| Content-Type | application/x-www-form-urlencoded |
Another header we send in the POST requests is Content-Type: application/x-www-form-urlencoded which indicates the media type of the resource that we send to your server. The keys and values are encoded in key-value tuples separated by '&', with an '=' between the key and the value. The non-alphanumeric characters in both keys and values are percent encoded. Here is an example request:
Payload data#
The Payload data holds all the relevant information regarding the event concerned, in the following structure:
| Data | Description |
|---|---|
| id | Unique alpha-numeric string that is generated for each sent event |
| created | Unix timestamp of the event |
| type | The type of event |
| resource | Array of all the information connected to the resource/operation that you receive for each event |
Events#
When configuring webhooks, you can choose one or several events that you would like to receive payloads for. The following section offers more details about each webhook and event in our Platform.
Account Webhooks#
Account webhooks are fired to notify you of events that occur whenever an operation concerning our Accounts Service is taking place. Usually, they are used to inform the merchant of the most important actions their customers had performed using their accounts.
Below you can find an illustration of the account webhooks within our platform.
customer.registered#
| Webhook Type | Description |
|---|---|
customer.registered | Fired to notify you that a new customer is registered |
Example Payload Data:
customer.updated#
| Webhook Type | Description |
|---|---|
customer.updated | Fired to notify you that data regarding an existing customer of yours have been updated |
Example Payload Data:
customer.password.updated#
| Webhook Type | Description |
|---|---|
customer.password.updated | Fired to notify that a customer of yours has updated their password |
Example Payload Data:
Access Webhooks#
The access webhooks are fired to notify you of events that occur whenever an operation concerning the Asset Access is taking place.
access.granted#
| Type | Description |
|---|---|
asset.access.granted | Fired to notify you that a customer has been granted access to your asset |
Example Payload Data:
access.revoked#
| Type | Description |
|---|---|
asset.access.revoked | Fired to notify you when a customer's access to your asset has been revoked |
Example Payload Data:
Payment Webhooks#
These events are fired to notify you of events that occur whenever operations concerning Payments are taking place.
payment.card.success#
| Type | Description |
|---|---|
payment.card.success | Fired to notify you that a customer of yours has made a successful payment |
Example Payload Data:
payment.card.failed#
| Type | Description |
|---|---|
payment.card.failed | Fired to notify that a customer of yours has made an unsuccessful payment attempt |
Example Payload Data:
payment.refund.success#
| Type | Description |
|---|---|
payment.refund.success | Fired to notify you that a customer of yours has been refunded |
Example Payload Data:
payment.refund.failed#
| Type | Description |
|---|---|
payment.refund.failed | Fired to notify you that the attempt for refunding a customer has failed |
Example Payload Data:
Subscription Webhooks#
These webhooks are fired to notify you of events that occur whenever operations concerning Recurring Subscriptions are taking place.
subscribe.success#
| Type | Description |
|---|---|
subscribe.success | Fired to notify you that a customer has subscribed to your asset successfully |
Example Payload Data:
subscribe.failed#
| Type | Description |
|---|---|
subscribe.failed | Fired to notify you that a customer's attempt to subscribe has failed |
Example Payload Data:
subscribe.cancelled.success#
| Type | Description |
|---|---|
subscribe.cancelled.success | Fired to notify you that a subscribed customer of yours has canceled the subscription successfully |
Example Payload Data:
subscribe.cancelled.failed#
| Type | Description |
|---|---|
subscribe.cancelled.failed | Fired to notify you that a customer's attempt to cancel the subscription has failed |
Example Payload Data:
subscribe.updated#
| Type | Description |
|---|---|
subscribe.updated | Fired to notify you that a subscribed customer has updated their billing agreement successfully |
Example Payload Data:
subscribe.expired#
| Type | Description |
|---|---|
subscribe.expired | Fired to notify you that a certain subscriber of yours has reached the subscription's expiration date |
Example Payload Data:
External Payment Webhooks#
These webhooks are fired to notify you of events that occur whenever operations involving External Payments are taking place.
external.payment.success#
| Type | Description |
|---|---|
external.payment.success | Fired to notify you that a customer has made a successful payment via PayPal or other external payment method |
Example Payload Data:
external.payment.failed#
| Type | Description |
|---|---|
external.payment.failed | Fired to notify you that a customer has unsuccessfully tried to complete payment via PayPal or other external payment method to gain access to your asset |
Example Payload Data:
external.payment.refund.success#
| Type | Description |
|---|---|
external.payment.refund.success | Fired to notify you that a customer of yours, who has accessed your asset via external payment, has been refunded successfully |
Example Payload Data:
external.payment.refund.failed#
| Type | Description |
|---|---|
external.payment.refund.failed | Fired to notify you that the attempt for refunding a customer of yours, who has accessed your asset via external payment, has been unsuccessful |
Example Payload Data:
External Subscription Webhooks#
These webhooks are fired to notify you of events that occur whenever operations involving External Subscriptions are taking place.
external.subscribe.success#
| Type | Description |
|---|---|
external.subscribe.success | Fired to notify you that a customer has made a successful subscription via PayPal or other external payment method |
Example Payload Data:
external.subscribe.failed#
| Type | Description |
|---|---|
external.subscribe.failed | Fired to notify you that a customer has made an unsuccessful attempt to subscribe to your asset using PayPal or other external payment method |
Example Payload Data:
external.subscribe.cancel.success#
| Type | Description |
|---|---|
external.subscribe.cancel.success | Fired to notify you that the subscription of a customer of yours who has been subscribed to your asset via PayPal or other external payment method is cancelled successfully |
Example Payload Data:
external.subscribe.cancel.failed#
| Type | Description |
|---|---|
external.subscribe.cancel.failed | Fired to notify you that a customer of yours, subscribed to your asset externally, has unsuccessfully tried to cancel the subscription |
Example Payload Data:
external.subscribe.update.success#
| Type | Description |
|---|---|
external.subscribe.update.success | Fired to notify you that a subscriber of yours has updated the billing agreement successfully via PayPal or other external payment method |
Example Payload Data:
external.subscribe.update.failed#
| Type | Description |
|---|---|
external.subscribe.update.failed | Fired to notify you that a subscriber of yours has unsuccessfully tried to update the billing agreement via PayPal or other external payment method |
Example Payload Data:
Securing Webhooks#
Once you start receiving webhooks, make sure the requests you have received are coming only from InPlayer. Some of the popular methods to confirm this include restriction per domain or the IP address from where you receive the requests. At InPlayer, we insist that you use the InPlayer signature to validate the event.
In order to use the signature for validation, first you need to have an API secret generated. To do so, navigate to the InPlayer’s dashboard and choose the 'API Settings' section.
Once the secret is generated, you can use it in your backend application to validate the event concerned.
Validating Events#
After you have your secret code set up, InPlayer will use it for generating a hash signature for each event that is to be sent as a header, along with every request as 'X-InPlayer-Signature'.
Once you receive an event and find the signature header, you should create a HASH using the same secret token and then compare your hash to the InPlayer signature header value. If both have the same values, you can take that as a validation proof that the event has been sent from InPlayer.
Here it is a PHP example of validating an event while using the signature comparison method:
You can implement the validation in any backend programming language. However, all implementations should have the following two things in common:
Regardless which implementation you use, the hash signature starts with
sha256=, using the key of your secret token and your payload body.Using a plain '==' operator is not advised. Rather, you can use a method like
hash_equalswhich performs a 'constant time' string comparison that renders the comparison safe from certain timing attacks against regular equality operators.