Webhooks allow interaction between web-based applications through the use of custom callbacks. In addition, Webhooks allow web applications to communicate with other web apps automatically.
Configuration
You can configure webhooks by going to Studio > Webhooks. Once you enter the calling endpoint and select the events you wish to receive, you're all set up on our end.
Return a 2xx response
Your endpoint must quickly return a successful status code (2xx) before any complex logic that could cause a timeout. For example, you must return a 200 response before adding a customer's transaction to your accounting system.
Soundee attempts to deliver your webhooks for up to three days with exponential backoff. If your endpoint has been disabled or deleted when we attempt a retry, future retries of that event will be prevented. However, if you disable and then re-enable a webhook endpoint before we're able to retry, you should still expect to see future retry attempts.
Signature verification (optional)
Soundee signs the webhook events to your endpoints by including a signature in each event's Soundee-Signature header. This allows you to verify that the events were sent by Soundee and not by a third party.
Before you can verify signatures, you need to retrieve your endpoint's application key from your Dashboard's Webhooks settings. First, go to your settings, then click the Reveal key button.
To verify the call, you first need to hash the payload through encryption with your application key as the secret. For example, in PHP, it would look like this:
$hash = base64_encode(hash_hmac('sha256', $payloadJSON, $yourApplicationKey));Now you can check if the Soundee-Signature is equal to your hash.
if($hash === $_SERVER['HTTP_SOUNDEE_VERIFICATION']){
// ok
} else {
// not by soundee..
}Logs
In Studio > Dashboard, you can see an overview of all webhook calls made. As soon as the call is successful, you will see the status code "success." As soon as the call is unsuccessful, you will see "failed."
For each call, you can view it's payload by clicking on it:
Event example codes
The following examples show what our data structure looks like for each event:
Sale succeeded
When you make a successful sale.
{
"type": "sale.succeeded",
"created": 1638219229,
"object": {
"amount": 30,
"commission": 0,
"country": {
"countryCode": "US",
"countryCode3": "USA",
"countryName": "United States"
},
"customer": {
"id": "27087",
"firstName": "John",
"lastName": "Doe",
"phone": "",
"email": "john.doe@gmail.com",
"new": false
},
"created": 1638219227,
"fee": 1.16,
"ip": "174.249.61.30",
"items": [
{
"type": "track",
"name": "Beat Title",
"amount": 30,
"tax": 0,
"net": 30,
"productId": 628,
"entityId": 862,
"license": {
"id": 1286,
"name": "Regular",
"exclusive": false
}
}
],
"location": "Soundee Store",
"net": "28.84",
"paymentSource": "Stripe",
"receiptUrl": "https://soundee.com/receipt/ch_3K1Gr8IoZYJzajdKDAIFX17O/a9503286e0534f8dd2cb928091aedfc1",
"status": "Completed",
"tax": {
"amount": 0,
"rate": 0
},
"transactionId": "ch_3K1Gr8IoZYJzajdKDAIFX17O",
"type": "payment"
}
}Entity deleted
When a track, kit, or service gets deleted.
{
"type": "entity.deleted",
"created": 1638214315,
"object": {
"entityId": 72294
}
}Entity created/Entity updated.
When a track, kit, or service gets updated.
{
"type": "entity.created",
"created": 1639088202,
"object": {
"artwork": [
{
"size": 50,
"url": "https:\/\/cdn.soundee.com\/avatars\/600ed88f46d5c-50x50.jpg"
},
{
"size": 100,
"url": "https:\/\/cdn.soundee.com\/avatars\/600ed88f46d5c-100x100.jpg"
},
{
"size": 200,
"url": "https:\/\/cdn.soundee.com\/avatars\/600ed88f46d5c-200x200.jpg"
},
{
"size": 300,
"url": "https:\/\/cdn.soundee.com\/avatars\/600ed88f46d5c-300x300.jpg"
},
{
"size": 600,
"url": "https:\/\/cdn.soundee.com\/avatars\/600ed88f46d5c-600x600.jpg"
}
],
"collaborators": null,
"bpm": 80,
"created": 1639088202,
"description": "",
"entityId": "73149",
"genre": "R&B",
"id": 43510,
"key": "",
"moods": [],
"price": 0,
"private": false,
"published": false,
"url": "https:\/\/soundee.com\/scarecrowbeats\/scarecrow-beats-jah-guidance-icefromsxm-collab",
"scale": "",
"title": "Scarecrow Beats - Jah Guidance (IceFromSXM Collab)",
"taggedFile": "https:\/\/cdn.soundee.com\/tracks\/81061b26388037.79220346\/2861b7070348b.mp3",
"tags": [],
"type": "track",
"youtubeUrl": ""
}
}