Overview

When building applications using Contiguity’s API, you might want your applications to receive events as they occur. This way, you can automatically trigger reactions to certain events.

Webhooks are extremely powerful — for example, you could to automatically send a thank you message to a user when they successfully verify their identity. Or, you could build a chatbot that replies to incoming messages.

​

Getting Started

To get started with Contiguity Webhooks, you’ll need to:

1. Create a webhook endpoint that receives POST requests and is secured with HTTPS.
2. Test your webhook endpoint by sending a test request with sample data.
3. Register your webhook endpoint with Contiguity using the Dashboard or API.

​

Creating a Webhook Endpoint

• Node.js
• Python
• Go
• Ruby

const express = require('express');
const app = express();
app.use(express.json());

app.post('/contiguity/webhook', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'communications.incoming.sms':
      // Handle incoming SMS
      console.log('Received SMS:', event.data);
      break;
    
    case 'communications.incoming.imessage':
      // Handle incoming iMessage
      console.log('Received iMessage:', event.data);
      break;
    
    case 'identity.verification_session.verified':
      // Handle verified identity session
      console.log('Identity verified:', event.data);
      break;

    default:
      console.log('Unhandled event:', event.type);
  }

  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

​

Best Practices

​

Quickly return a 2xx response

Your webhook endpoint must quickly return a 2xx response (any successful HTTP status code) to Contiguity. If your webhook endpoint takes too long to respond, Contiguity may assume it’s failed and retry sending the event at a later time.* For example, you should return a response before processing and replying to a user’s message.

​

Handle events asynchronously

Configure your webhook endpoint to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries (for example, increased incoming messages or more identity verifications than usual) might overwhelm your endpoint host. Asynchronous queues allow you to process the concurrent events at a rate your system can support.