How can we help? 👋

Webhook Integration

How to use webhooks with Senja

Welcome to the Senja Webhook documentation 👋

Webhooks are a powerful tool for integrating different applications and services.

 

By using webhooks, you can automate workflows and receive real-time updates from other systems.

Now you can easily set up webhooks to receive notifications and trigger actions based on events that occur in Senja.

 

In this documentation, we'll walk you through how to use webhooks with Senja. Let's get started! 👍

Notion image

Anatomy of Senja’s Webhooks

Webhooks consist of several key components:

  • Webhook URL: This is the URL to which the webhook payload will be sent when an event occurs.
  • Secret: This is an optional field that can be used to verify that the webhook was sent by Senja. When you set up a webhook, you can choose to include a secret in the payload. Senja will then sign the payload using this secret, and you can use it to verify that the payload was sent by Senja and has not been tampered with. All webhooks sent by Senja include a x-senja-signature header. Senja generates this header using a keyed-hash message authentication code (HMAC) with SHA256 and the secret key that you provide. Below is example NodeJS code that demonstrates how to verify the signature.
import crypto from 'crypto';

function createHmacSignature(secret: string, payload: string) {
	const hmac = crypto.createHmac('sha256', secret);
	hmac.update(payload);
	return hmac.digest('hex');
}

function verifyHmacSignature(secret: string, payload: string, signature: string) {
	return createHmacSignature(secret, payload) === signature;
}

const secret = 'YOUR SECRET';
const payload = req.body;
const signature = req.headers['x-senja-signature'];
const isValid = verifyHmacSignature(secret, JSON.stringify(payload), signature);
  • Events: These are the events that you want to listen to. When an event occurs in your application, Senja will send a payload to the webhook URL that you specify. The payload will contain information about the event, such as the type of event and any associated data.

By specifying the webhook URL, secret (if desired), and events that you want to listen to, you can configure Senja to send webhook payloads to your application whenever specific events occur. This can be a powerful way to automate workflows and streamline your application's functionality.

Where to edit your Webhook

Click on the automate tab on the sidebar and scroll down.

You can also find this in your project settings.

Notion image

Webhook Events

Note: for complete details about the fields in the testimonial in the data of the payload, see our REST API documentation.

testimonial_created

This event is triggered when a new testimonial is created in Senja.

The payload will contain information about the testimonial, such as the endorser, text, and date created.

You can use this event to do things like automatically tag someone who sends you a testimonial in your CRM.

Example Payload:

{
  "type": "testimonial_created",
  "data": {
    "new": {
      "id": "bb0c81be-925f-456d-b636-ae1d93680007",
      "type": "text",
      "integration": null,
      "title": null,
      "text": "I absolutely love Senja! It's hands-down, the best testimonial platform I've ever used.",
      "rating": null,
      "media": [],
      "url": null,
      "date": "2023-05-15T15:39:23.545Z",
      "approved": false,
      "project_id": "7db5d354-6556-4f88-b29a-99e9552ca906",
      "thumbnail_url": null,
      "form_id": "766f9d68-198e-489e-abd6-d66bb877922b",
      "customer_name": "John Doe",
      "customer_email": "john@placeholder.com",
      "customer_avatar": "https://senjaio.b-cdn.net/public/avatar/d24ae65d-ef5e-473f-9818-43302c3c8813_avatar.webp",
      "customer_tagline": "Marketing at Placeholder",
      "customer_username": null,
      "customer_url": "https://placeholder.com"
      "created_at": "2023-05-15T15:39:23.545+00:00",
      "tags": []
    }
  }
}

testimonial_updated

This event is triggered when an existing testimonial in Senja is updated.

The payload will contain information about the updated testimonial, such as the approval status, the updated text etc.

You can use this event to do things like automatically publish a testimonial to social media when a testimonial has been approved

{
  "type": "testimonial_updated",
  "data": {
    "old": {
      "id": "bb0c81be-925f-456d-b636-ae1d93680007",
      "type": "text",
      "integration": null,
      "title": null,
      "text": "I absolutely love Senja! It's hands-down, the best testimonial platform I've ever used.",
      "rating": null,
      "media": [],
      "url": null,
      "date": "2023-05-15T15:39:23.545Z",
      "approved": false,
      "project_id": "7db5d354-6556-4f88-b29a-99e9552ca906",
      "thumbnail_url": null,
      "form_id": "766f9d68-198e-489e-abd6-d66bb877922b",
      "customer_name": "John Doe",
      "customer_email": "john@placeholder.com",
      "customer_avatar": "https://senjaio.b-cdn.net/public/avatar/d24ae65d-ef5e-473f-9818-43302c3c8813_avatar.webp",
      "customer_tagline": "Marketing at Placeholder",
      "customer_username": null,
      "customer_url": "https://placeholder.com"
      "created_at": "2023-05-15T15:39:23.545+00:00",
      "tags": []
    },
    "new": {
      "id": "bb0c81be-925f-456d-b636-ae1d93680007",
      "type": "text",
      "integration": null,
      "title": null,
      "text": "I absolutely love Senja! It's hands-down, the best testimonial platform I've ever used.",
      "rating": null,
      "media": [],
      "url": null,
      "date": "2023-05-15T15:39:23.545Z",
      "approved": true,
      "project_id": "7db5d354-6556-4f88-b29a-99e9552ca906",
      "thumbnail_url": null,
      "form_id": "766f9d68-198e-489e-abd6-d66bb877922b",
      "customer_name": "John Doe",
      "customer_email": "john@placeholder.com",
      "customer_avatar": "https://senjaio.b-cdn.net/public/avatar/d24ae65d-ef5e-473f-9818-43302c3c8813_avatar.webp",
      "customer_tagline": "Marketing at Placeholder",
      "customer_username": null,
      "customer_url": "https://placeholder.com"
      "created_at": "2023-05-15T15:39:23.545+00:00",
      "tags": []
    }
  }
}

testimonial_deleted

This event is triggered when a testimonial is deleted in Senja.

The payload will contain information about the deleted testimonial, such as the endorser and the text.

{
  "type": "testimonial_deleted",
  "data": {
    "old": {
      "id": "6c404d18-3cd3-4995-a069-4e20f3024a51",
      "type": "text",
      "integration": null,
      "title": null,
      "text": "I absolutely love Senja. It's the best testimonial tool in existence currently",
      "rating": null,
      "media": [],
      "url": null,
      "date": "2023-05-15T15:36:30.613Z",
      "approved": false,
      "project_id": "7db5d354-6556-4f88-b29a-99e9552ca906",
      "thumbnail_url": null,
      "form_id": "766f9d68-198e-489e-abd6-d66bb877922b",
			"customer_name": "John Doe",
      "customer_email": "john@placeholder.com",
      "customer_avatar": "https://senjaio.b-cdn.net/public/avatar/d24ae65d-ef5e-473f-9818-43302c3c8813_avatar.webp",
      "customer_tagline": "Marketing at Placeholder",
      "customer_username": null,
      "customer_url": "https://placeholder.com"
      "created_at": "2023-05-15T15:36:30.613+00:00",
      "tags": []
    }
  }
}
Did this answer your question?
😞
😐
🤩