# Verifying webhooks with the Svix libraries (Recommended)

Each webhook call includes three headers with additional information used for verification:

* **svix-id**: The unique message identifier for the webhook message. This identifier is unique across all messages but will remain the same when the same webhook is being resent (e.g., due to a previous failure).
* **svix-timestamp**: The timestamp in seconds since the epoch.
* **svix-signature**: The Base64-encoded list of signatures, space-delimited.

***

First install the libraries if you haven't already:

{% tabs fullWidth="false" %}
{% tab title="JavaScript" %}

```
npm install svix
// Or
yarn add svix
```

{% endtab %}

{% tab title="Python" %}

```
pip install svix
```

{% endtab %}

{% tab title="Rust" %}

```
http = "1.0.0"
svix = "1.20.0"
```

{% endtab %}

{% tab title="Go" %}

```
go get github.com/svix/svix-webhooks/go
```

{% endtab %}

{% tab title="Java" %}
Gradle: Add this dependency to your project's build file:

```
implementation "com.svix:svix:0.x.y"
```

Maven: Add this dependency to your project's POM:

```
<dependency>
  <groupId>com.svix</groupId>
  <artifactId>svix</artifactId>
  <version>0.x.y</version>
</dependency>
```

{% endtab %}

{% tab title="Kotlin" %}
Gradle: Add this dependency to your project's build file:

```
implementation "com.svix.kotlin:svix-kotlin:0.x.y"
```

Maven: Add this dependency to your project's POM:

```
<dependency>
  <groupId>com.svix.kotlin</groupId>
  <artifactId>svix-kotlin</artifactId>
  <version>0.x.y</version>
</dependency>
```

{% endtab %}

{% tab title="Ruby" %}

```
gem install svix
```

{% endtab %}

{% tab title="C#" %}

```
dotnet add package Svix
```

{% endtab %}

{% tab title="PHP" %}

```
composer require svix/svix
```

{% endtab %}

{% tab title="CLI" %}
On macOS install via [Homebrew](https://brew.sh/):

```
brew install svix/svix/svix-cli
```

On Windows install via [Scoop](https://scoop.sh/):

```
scoop bucket add svix https://github.com/svix/scoop-svix.git
scoop install svix
```

For other platforms, such as linux, checkout the [CLI docs](https://github.com/svix/svix-cli#installation) on Github.
{% endtab %}

{% tab title="cURL" %}

```
# Install cURL. E.g. on arch linux:
pacman -S curl
```

{% endtab %}
{% endtabs %}

Then verify webhooks using the code below. The payload is the raw (string) body of the request, and the headers are the headers passed in the request.

{% hint style="warning" %}
**USE THE RAW REQUEST BODY**

You need to use the raw request body when verifying webhooks, as the cryptographic signature is sensitive to even the slightest changes. You should watch out for frameworks that parse the request as JSON and then stringify it because this too will break the signature verification.
{% endhint %}

## Framework specific examples <a href="#framework-specific-examples" id="framework-specific-examples"></a>

Here are examples of how to adjust the above examples to your framework of choice.

### Python (Django) <a href="#python-django" id="python-django"></a>

```python
from django.http import HttpResponse

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@csrf_exempt
def webhook_handler(request):
    headers = request.headers
    payload = request.body

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return HttpResponse(status=400)

    # Do something with the message...

    return HttpResponse(status=204)
```

### Python (Flask) <a href="#python-flask" id="python-flask"></a>

```python
from flask import request

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@app.route('/webhook/')
def webhook_handler():
    headers = request.headers
    payload = request.get_data()

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return ('', 400)

    # Do something with the message...

    return ('', 204)
```

### Python (FastAPI) <a href="#python-fastapi" id="python-fastapi"></a>

```python
from fastapi import Request, Response, status

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@router.post("/webhook/", status_code=status.HTTP_204_NO_CONTENT)
async def webhook_handler(request: Request, response: Response):
    headers = request.headers
    payload = await request.body()

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        response.status_code = status.HTTP_400_BAD_REQUEST
        return

    # Do something with the message...
```

### Node.js (Next.js) <a href="#nodejs-nextjs" id="nodejs-nextjs"></a>

The [svix-example](https://github.com/svix/svix-example) repo contains an [example](https://github.com/svix/svix-example/blob/main/src/pages/api/consumer/webhooks.ts) of how to verify and use webhooks in a Next.js application.

```js
import { Webhook } from "svix";
import { buffer } from "micro";

export const config = {
    api: {
        bodyParser: false,
    },
}

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

export default async function handler(req, res) {
    const payload = (await buffer(req)).toString();
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
}
```

### Node.js (Next.js 13 App Router) <a href="#nodejs-nextjs-13-app-router" id="nodejs-nextjs-13-app-router"></a>

```js
import { Webhook } from "svix";

const webhookSecret: string = process.env.WEBHOOK_SECRET || "your-secret";

export async function POST(req: Request) {
  const svix_id = req.headers.get("svix-id") ?? "";
  const svix_timestamp = req.headers.get("svix-timestamp") ?? "";
  const svix_signature = req.headers.get("svix-signature") ?? "";

  const body = await req.text();

  const sivx = new Webhook(webhookSecret);

  let msg;

  try {
    msg = sivx.verify(body, {
      "svix-id": svix_id,
      "svix-timestamp": svix_timestamp,
      "svix-signature": svix_signature,
    });
  } catch (err) {
    return new Response("Bad Request", { status: 400 });
  }

  console.log(msg);

  // Rest

  return new Response("OK", { status: 200 });
}
```

### Node.js (Netlify Functions) <a href="#nodejs-netlify-functions" id="nodejs-netlify-functions"></a>

```js
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";


export const handler = async ({body, headers}) => {
    const payload = body;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
}
```

### Node.js (Express) <a href="#nodejs-express" id="nodejs-express"></a>

**Note:** When integrating this example into a larger codebase, you will have to make sure not to apply the `express.json()` middleware to the webhook route, because the payload has to be passed to `wh.verify` without any prior parsing.

```js
import { Webhook } from "svix";
import bodyParser from "body-parser";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

app.post('/webhook', bodyParser.raw({ type: 'application/json' }), (req, res) => {
    const payload = req.body;
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
});
```

### Node.js (NestJS) <a href="#nodejs-nestjs" id="nodejs-nestjs"></a>

Initialize the application with the `rawBody` flag set to true. See the [NestJS docs](https://docs.nestjs.com/faq/raw-body#raw-body) for details.

```js
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(
    AppModule,
    { rawBody: true } // add rawBody flag
  );
  await app.listen(3000);
}
bootstrap();

```

```js
// webhook.controller.ts
import { Controller, Post, RawBodyRequest, Req } from '@nestjs/common';
import { Request } from 'express';
import { Webhook } from 'svix';

@Controller('webhook')
class WebhookController {
  @Post()
  webhook(@Req() request: RawBodyRequest<Request>) {
    const secret = 'whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw';
    const wh = new Webhook(secret);

    const payload = request.rawBody.toString('utf8');
    const headers = request.headers;

    let msg;
    try {
      msg = wh.verify(payload, headers);
    } catch (err) {
      // handle error
    }

    // Do something with the message...
  }
}

```

### Node.js (Nuxt) <a href="#nodejs-nuxt" id="nodejs-nuxt"></a>

```js
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

export default defineEventHandler(async (event) => {
  const headers = getRequestHeaders(event);
  const payload = await readRawBody(event);

  const wh = new Webhook(secret);

  let msg;

  try {
      msg = wh.verify(payload, headers);
  } catch (err) {
      setResponseStatus(event, 400);
      return "Bad Request";
  }

  // Do something with the message...
  return "OK";
})
```

### Go (Standard lib) <a href="#go-standard-lib" id="go-standard-lib"></a>

```go
package main

import (
	"io"
	"log"
	"net/http"

	svix "github.com/svix/svix-webhooks/go"
)

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

func main() {

	wh, err := svix.NewWebhook(secret)
	if err != nil {
		log.Fatal(err)
	}

	http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
		headers := r.Header
		payload, err := io.ReadAll(r.Body)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		err = wh.Verify(payload, headers)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		// Do something with the message...

		w.WriteHeader(http.StatusNoContent)

	})
	http.ListenAndServe(":8080", nil)
}
```

### Go (Gin) <a href="#go-gin" id="go-gin"></a>

```go
package main

import (
	"io"
	"log"
	"net/http"

	"github.com/gin-gonic/gin"
	svix "github.com/svix/svix-webhooks/go"
)

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

func main() {

	wh, err := svix.NewWebhook(secret)
	if err != nil {
		log.Fatal(err)
	}

	r := gin.Default()
	r.POST("/webhook", func(c *gin.Context) {
		headers := c.Request.Header
		payload, err := io.ReadAll(c.Request.Body)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		err = wh.Verify(payload, headers)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// Do something with the message...

		c.JSON(200, gin.H{})
	})
	r.Run()
}
```

### Rust (axum) <a href="#rust-axum" id="rust-axum"></a>

Add the `webhook_in` route below to an axum router.

```rust
use axum::{body::Bytes, http::StatusCode};
use hyper::HeaderMap;

pub const SECRET: &'static str = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

pub async fn webhook_in(headers: HeaderMap, body: Bytes) -> StatusCode {
    let Ok(wh) = svix::webhooks::Webhook::new(SECRET) else {
        return StatusCode::INTERNAL_SERVER_ERROR;
    };

    if let Err(_) = wh.verify(&body, &headers) {
        return StatusCode::BAD_REQUEST;
    }

    // Do something with the message...

    StatusCode::NO_CONTENT
}
```

### Ruby (Ruby on Rails) <a href="#ruby-ruby-on-rails" id="ruby-ruby-on-rails"></a>

Once you've set up your project add a route to your `config/routes.rb` file at the top of the `Rails.application.routes.draw` block:

```ruby
Rails.application.routes.draw do
  post "/webhook", to: "webhook#index"

  # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
end
```

The route above declares that `POST /webhook` requests are mapped to the index action of `WebhookController`.

To create `WebhookController` and its index action, we'll run the controller generator (with the `--skip-routes` option because we already have an appropriate route):

```
bin/rails generate controller Webhook index --skip-routes
```

Rails will create several files for you:

```ruby
    create  app/controllers/webhook_controller.rb
    invoke  erb
    create    app/views/webhook
    create    app/views/webhook/index.html.erb
    invoke  test_unit
    create    test/controllers/webhook_controller_test.rb
    invoke  helper
    create    app/helpers/webhook_helper.rb
    invoke    test_unit
    invoke  assets
    invoke    scss
    create      app/assets/stylesheets/webhook.scss
```

Now we can add our verification logic to the newly created `app/controllers/webhook_controller.rb` file:

```ruby
require 'svix'

class WebhookController < ApplicationController
  protect_from_forgery with: :null_session # disables CSRF middleware; required for API endpoints

  def index
    begin
      payload = request.body.read
      headers = request.headers
      wh = Svix::Webhook.new("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw")

      json = wh.verify(payload, headers)

      # Do something with the message...

      head :no_content
    rescue
      head :bad_request
    end
  end
end
```

### PHP (Laravel) <a href="#php-laravel" id="php-laravel"></a>

In your `routes/api.php` file add the following after the last use directive:

```php
use Svix\Webhook;
use Svix\Exception\WebhookVerificationException;

Route::post('webhook', function(Request $request) {
    $payload = $request->getContent();
    $headers = collect($request->headers->all())->transform(function ($item) {
        return $item[0];
    });

    try {
        $wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw");
        $json = $wh->verify($payload, $headers);

        # Do something with the message...

        return response()->noContent();
    } catch (WebhookVerificationException $e) {
        return response(null, 400);
    }
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.txn.io/api-basics/webhooks/verifying-webhooks-with-the-svix-libraries-recommended.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.