Webhooks

​

Webhooks in PlanetScale

​

Common webhook use cases

• Creating notifications in Slack, Microsoft Teams, GitHub, and other tools
• Integrating with CI/CD processes for the automation of schema changes
• Updating external issue trackers like Jira

​

Setting up a webhook in PlanetScale

​

Handling deliveries

• You must receive events with an HTTPS server.
• Your server must quickly respond with a 2xx successful status code to indicate that the webhook was received successfully.
• PlanetScale will not follow any redirects from the server.
• PlanetScale’s webhooks will originate from one of the following IP addresses:
  Copy

  Ask AI

  3.209.149.66
  3.215.97.46
  34.193.111.15
  

• We recommend validating all webhook signatures to ensure the webhook came from PlanetScale, not from a third party, and was not tampered with.

​

Responding to webhooks quickly

​

Limits

• Each database can have up to 5 webhooks. If you need more webhooks per database, please contact us.
• You can only send one webhook test every 20 seconds.
• Webhooks that repeatedly fail will be disabled.

​

Validating a webhook signature

1. Retrieve your webhook secret from PlanetScale. Go to your database’s settings page > “Webhooks” page. Click the … ellipsis next to the webhook you want to validate and click “Show secret”.
2. Copy and securely store your webhook secret on your server. Never hard code the secret into your application or check it into source control. Follow the best practices for your deployment provider and framework for storing secrets.
3. Validate incoming webhook payloads against the secret to verify that the payload was sent by PlanetScale. You should calculate a hash using the JSON payload and the webhook secret. Then, compare the calculated hash to the X-PlanetScale-Signature header. If the two hashes match, the webhook payload is valid.

​

Example webhook signature validation

​

JavaScript

const crypto = require('crypto')

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET

const verify_signature = (req) => {
  const signature = crypto.createHmac('sha256', WEBHOOK_SECRET).update(JSON.stringify(req.body)).digest('hex')
  const trusted = Buffer.from(signature, 'ascii')
  const header = req.headers.get('x-planetscale-signature')

  if (header === undefined) {
    return false
  }

  const untrusted = Buffer.from(header)
  return crypto.timingSafeEqual(trusted, untrusted)
}

const app = express()
app.use(bodyParser.raw({ inflate: true, type: 'application/json' }))

​

TypeScript

import crypto from 'crypto'

const WEBHOOK_SECRET: string = process.env.WEBHOOK_SECRET

const verify_signature = (req: Request): boolean => {
  const signature = crypto.createHmac('sha256', WEBHOOK_SECRET).update(JSON.stringify(req.body)).digest('hex')
  const trusted = Buffer.from(signature, 'ascii')
  const header = req.headers.get('x-planetscale-signature')

  if (header === undefined) {
    return false
  }

  const untrusted = Buffer.from(header)
  return crypto.timingSafeEqual(trusted, untrusted)
}

const handleWebhook = (req: Request, res: Response) => {
  if (!verify_signature(req)) {
    res.status(401).send('Unauthorized')
    return
  }
  // The rest of your logic here
}

​

Python

from flask import Flask, request
from hashlib import sha256
import hmac

app = Flask(__name__)

# Use the PLANETSCALE_WEBHOOK_SECRET environment variable to set the secret token
SECRET_TOKEN = os.environ.get('PLANETSCALE_WEBHOOK_SECRET', 'default_secret_token')

@app.route('/webhook', methods=['POST'])
def webhook():
    payload_body = request.data
    signature_header = request.headers.get('x-planetscale-signature')

    try:
        verify_signature(payload_body, SECRET_TOKEN, signature_header)
        # The signature is valid, you can process the payload here
        return "Signature is valid."
    except Exception as e:
        # Handle the verification failure here
        return str(e), 403

def verify_signature(payload_body, secret_token, signature_header):
    if not signature_header:
        raise Exception("x-planetscale-signature header is missing!")

    hash_object = hmac.new(secret_token.encode('utf-8'), msg=payload_body, digestmod=sha256)
    expected_signature = hash_object.hexdigest()

    if not hmac.compare_digest(expected_signature, signature_header):
        raise Exception("Request signatures didn't match!")

if __name__ == '__main__':
    app.run(debug=True)

​

Ruby on Rails

SECRET = Rails.application.credentials.planetscale.fetch(:webhook_secret)

# Private method in your controller
def verify_signature
  body = request.body.read
  signature = request.headers["X-PlanetScale-Signature"]

  calculated_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), SECRET, body)

  unless ActiveSupport::SecurityUtils.secure_compare(signature, calculated_signature)
    render(json: { message: "Unauthorized" }, status: :unauthorized)
  end
end

before_action :verify_signature, only: [:create]

​

Need help?