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:

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

As of November 1st, 2024, webhook endpoints must be secured with HTTPS to protect sensitive data, like Identity verification reports. See Webhook Signing to verify payloads with HMAC-SHA256.

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;

    case 'facetime.call.answered':
      // Handle an answered FaceTime call
      console.log('FaceTime answered:', 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');
});

from flask import Flask, request
app = Flask(__name__)

@app.route('/contiguity/webhook', methods=['POST'])
def webhook():
    event = request.json

    match event['type']:
        case 'communications.incoming.sms':
            # Handle incoming SMS
            print(f"Received SMS: {event['data']}")
        
        case 'communications.incoming.imessage':
            # Handle incoming iMessage
            print(f"Received iMessage: {event['data']}")
        
        case 'identity.verification_session.verified':
            # Handle verified identity session
            print(f"Identity verified: {event['data']}")

        case 'facetime.call.answered':
            # Handle an answered FaceTime call
            print(f"FaceTime answered: {event['data']}")
            
        case _:
            print(f"Unhandled event: {event['type']}")

    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type Event struct {
    Type string                 `json:"type"`
    Data map[string]interface{} `json:"data"`
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    var event Event
    if err := json.NewDecoder(r.Body).Decode(&event); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    switch event.Type {
    case "communications.incoming.sms":
        // Handle incoming SMS
        fmt.Printf("Received SMS: %v\n", event.Data)
    
    case "communications.incoming.imessage":
        // Handle incoming iMessage
        fmt.Printf("Received iMessage: %v\n", event.Data)
    
    case "identity.verification_session.verified":
        // Handle verified identity session
        fmt.Printf("Identity verified: %v\n", event.Data)

    case "facetime.call.answered":
        // Handle an answered FaceTime call
        fmt.Printf("FaceTime answered: %v\n", event.Data)
        
    default:
        fmt.Printf("Unhandled event: %v\n", event.Type)
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte("OK"))
}

func main() {
    http.HandleFunc("/contiguity/webhook", webhookHandler)
    fmt.Println("Webhook server running on port 3000")
    http.ListenAndServe(":3000", nil)
}

require 'sinatra'
require 'json'

post '/contiguity/webhook' do
  event = JSON.parse(request.body.read)

  case event['type']
  when 'communications.incoming.sms'
    # Handle incoming SMS
    puts "Received SMS: #{event['data']}"
  
  when 'communications.incoming.imessage'
    # Handle incoming iMessage
    puts "Received iMessage: #{event['data']}"
  
  when 'identity.verification_session.verified'
    # Handle verified identity session
    puts "Identity verified: #{event['data']}"

  when 'facetime.call.answered'
    # Handle an answered FaceTime call
    puts "FaceTime answered: #{event['data']}"
  
  else
    puts "Unhandled event: #{event['type']}"
  end

  status 200
  body 'OK'
end

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.

*Contiguity does not guarantee webhook retries. If you do not respond to a webhook event, or respond with a non-2xx status code, Contiguity may not retry certain events, or stop sending events to your endpoint entirely.

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.

Getting Started

Text

Email

OTP

iMessage

FaceTime

Lease

Number Intelligence

Entitlements

Identity

WhatsApp

Getting Started

Creating a Webhook Endpoint

Best Practices

Quickly return a 2xx response

Handle events asynchronously

​Getting Started

​Creating a Webhook Endpoint

​Best Practices

​Quickly return a 2xx response

​Handle events asynchronously

Getting Started

Creating a Webhook Endpoint

Best Practices

Quickly return a 2xx response

Handle events asynchronously