At this stage we assume you have already created an API key. If you haven’t, please refer to the Introduction page.

To receive webhook events, you need to provide us with a URL that we can send the events to.

You can use a service like ngrok to create a secure tunnel to your local development environment.

To create a new webhook go to the Webhooks page.

After creating a webhook, you will receive a secret key that you can use to verify the webhook events.

After running ngrok wait a minute for DNS to resolve correctly. Otherwise, you may get an error.

​
Handling webhook events

Current webhook events are:

  • post.published - When a post is published to social media platforms.
  • comment.published - When a comment is published to social media platforms.
  • team.created - When a team is created.
  • team.updated - When a team is updated.
  • team.deleted - When a team is deleted.
  • social-account.created - When a social account is created.
  • social-account.updated - When a social account is updated.
  • social-account.deleted - When a social account is deleted.

If you are using the bundle.social SDK, you can use the webhook module to handle webhook events. Check it out

import crypto from 'crypto';

/**
 * Verify the signature of a webhook request
 * @param body - Stringified body of the webhook request
 * @param signature - The signature passed in the `x-signature` header
 * @param secret - The webhook secret used to sign the request
 * @returns Whether the signature is valid
 */
private verifySignature(
  body: string,
  signature: string,
  secret: string,
): boolean {
  // Create a hash using the body and the secret
  const sig = crypto.createHmac('sha256', secret).update(body).digest('hex');

  return sig === signature;
}

/**
 * Construct a webhook event from a request
 * @param rawBody - The raw body of the webhook request
 * @param signature - The signature passed in the `x-signature` header
 * @param secret - The webhook secret used to sign the request
 * @returns Parsed webhook event
 */
public constructEvent(rawBody: string, signature: string, secret: string) {
  const body = typeof rawBody === 'string' ? rawBody : JSON.stringify(rawBody);

if (!this.verifySignature(body, signature, secret)) {
  throw new Error('Invalid signature');
}

return JSON.parse(body);
}

Simple example using express

import express from 'express';

const app = express();

app.post('/webhook', express.json({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];

  let event;

  try {
    // Verify the webhook signature and return the event
    event = bundlesocial.webhooks.constructEvent(
      req.body,
      signature as string,
      secret,
    );
    // Do something with the event
  } catch (err) {
    console.log(`Webhook signature verification failed.`, err);
    return res.sendStatus(400);
  }

  return res.send();
});