Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with the Cocktail API. With webhooks, your app can receive real-time notifications about changes or events related to cocktails, ingredients, and more.

Registering Webhooks

To register a new webhook, you need to have a URL in your app that the Cocktail API can call. You can configure a new webhook via the Cocktail API dashboard under Webhook Settings. Give your webhook a name, select the events you want to receive notifications for, and provide your webhook URL.

Once registered, the Cocktail API will send a webhook request to your URL whenever an event of interest occurs. In the next section, we'll cover how to consume and handle these webhook requests.

Consuming Webhooks

When your app receives a webhook request from the Cocktail API, check the type attribute to determine the event that triggered the webhook. The type will specify the event, such as a new cocktail or ingredient update.

Example webhook payload

{
  "id": "abc123",
  "type": "cocktail.updated",
  "payload": {
    "id": "cocktail_001",
    "name": "Mojito",
    "ingredients": ["Mint", "Lime", "Sugar", "Rum"],
    "updated_at": "2024-08-24T12:34:56Z"
  }
}

In the example above, a conversation was updated, and the payload type is a conversation.

See all event types

Event types

Name
cocktail.created
Description
A new cocktail was created.
Name
cocktail.updated
Description
An existing cocktail was updated.
Name
cocktail.deleted
Description
A cocktail was successfully deleted.
Name
ingredient.created
Description
A new ingredient was added.
Name
ingredient.updated
Description
An existing ingredient was updated.
Name
ingredient.deleted
Description
An ingredient was successfully deleted.
Name
category.created
Description
A new category was created.
Name
category.updated
Description
An existing category was updated.
Name
category.deleted
Description
A category was successfully deleted.

Example payload

  {
    "id": "abc123",
    "type": "ingredient.updated",
    "payload": {
      "id": "ingredient_001",
      "name": "Lime",
      "quantity": "2",
      "updated_at": "2024-08-24T12:34:56Z"
    }
  }

Security

To know for sure that a webhook was, in fact, sent by Cocktail API instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-protocol-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

Verifying a request

const signature = req.headers['x-cocktail-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-protocol-signature header, you can be sure that the request was truly coming from Cocktail API. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Cocktail API. Don't commit your secret webhook key to GitHub!