A webhook is an endpoint that receives updates concerning your requests and actions happening on your application. When you create a new app, you are required to pass a webhook url which must return a 200 status code response.
Webhook verification
A webhook verification token is created for you when you create a new application. You should copy this value and save it as an environment variable in your application. Orchdio sends an x-orchdio-hmac header in the response header which is the calculated hash of the payload.
Using the webhook's verify token you'll calculate the SHA256 hash value of the payload and compare the value of the x-orchdio-hmac with your generated hash to assert the response has not been tampered with.
// TODO (javascript example)
const { hmac } = require('node:crypto')
// GenerateHMAC is an helper function to generate the SHA256 hash of a payload
// with a secret key.
func GenerateHMAC(message interface{}, secret string) []byte {
mac := hmac.New(sha256.New, []byte(secret))
payload, err := json.Marshal(message)
if err != nil {
log.Printf("Error serializing payload")
return nil
}
mac.Write(payload)
return []byte(hex.EncodeToString(mac.Sum(nil)))
}
// in your handler
// get the `x-orchdio-hmac` header from the response.
// we're using the go fiber framework here so it may be different from how you would
// do the same in your app.
hash := ctx.Get("x-orchdio-hmac")
payloadHmac := GenerateHMAC(payload, os.GetEnv("APP_VERIFY_SECRET"))
if payloadHmac == nil {
log.Println("Could not generate payload hmac")
// you might want to exit or return an error here
}
if hmac.Equal([]byte(payload), hash) {
log.Println("We've got a match. Payload verified")
}
Response format
A webhook response is in the format:
// Some code
{
"payload": "main response of this event",
"message": "a message accompanying this event",
"event": "the webhook event"
}
Events
The events supported currently are
playlist:conversion
Example Response
At the moment the webhook receives playlist conversion updates. A sample response is provided below.