Webhooks

Webhooks ermöglichen TeamMessage die Kommunikation mit Ihren Systemen über HTTP-Callbacks. Nutzen Sie sie für Nachrichtenzustellung, Status-Benachrichtigungen oder zum Weiterleiten von Nachrichten an externe Dienste.

Übersicht

TeamMessage unterstützt drei Arten von Webhooks:

• Webhook als Zustellkanal – Nachrichten von einer Teamliste an Ihren Server weiterleiten
• Sendeberichte – Benachrichtigungen erhalten, wenn SMS zugestellt werden oder fehlschlagen
• Eingehende SMS – Empfangene SMS an Ihren Server weiterleiten (sms2mail exklusiv)

Webhook als Zustellkanal

Fügen Sie eine Webhook-URL als Teammitglied hinzu, um alle Nachrichten an die Teamliste an Ihren Server weiterzuleiten. Dies ist nützlich für die Integration von TeamMessage mit Ticketing-Systemen, Chat-Plattformen oder eigenen Anwendungen.

Konfiguration

1. Öffnen Sie Ihre Teamliste → Mitglieder
2. Klicken Sie auf 'Mitglied hinzufügen'
3. Wählen Sie den Kanal: Webhook
4. Geben Sie Ihre Webhook-URL ein (muss mit https:// beginnen)

Anfrageformat

Wenn eine Nachricht an die Teamliste gesendet wird, sendet TeamMessage eine POST-Anfrage mit JSON:

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.example.com
Content-Type: application/json; charset=UTF-8

{
  "from": "+491711234567",
  "message": "This is the message text",
  "account_id": 123,
  "account_email": "alerts@tmsg.de",
  "recipient_name": "My Webhook",
  "timestamp": 1736694000
}

Parameter

Erwartete Antwort

Ihr Endpunkt sollte einen HTTP-2xx-Statuscode (200, 201, 204) zurückgeben, um Erfolg anzuzeigen:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "received"}

Anwendungsfälle

• Alarme an Slack, Microsoft Teams oder Discord weiterleiten
• Tickets in Jira, Zendesk oder anderen Ticketing-Systemen erstellen
• Protokollieren Sie Nachrichten in einer Datenbank oder einem Monitoring-SystemNachrichten in einer Datenbank oder einem Monitoring-System protokollieren
• Automatisierte Workflows auslösen (Zapier, n8n, Make)

Sendeberichte

Zustellbericht-Webhooks benachrichtigen Sie über den endgültigen Status gesendeter Nachrichten.

Konfiguration

Konfigurieren Sie eine Webhook-URL in Ihren Teamlisten-Einstellungen:

1. Gehen Sie zu den Teamlisten-Einstellungen
2. Geben Sie Ihre Webhook-URL im Feld 'Zustellbericht-URL' ein
3. Die URL muss ein gültiger HTTP- oder HTTPS-Endpunkt sein

Anfrageformat

TeamMessage sendet eine POST-Anfrage mit formular-kodierten Daten:

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.example.com
Content-Type: application/x-www-form-urlencoded

status=0&reason=0&to=004917012345678&msgid=123456&timestamp=2025-01-08T14:30:00Z

Parameter

Siehe Statuscodes für eine vollständige Liste der Status- und Reason-Codes.

Wiederholungsverhalten

Wenn Ihr Endpunkt nicht mit HTTP 200 antwortet:

• TeamMessage versucht es nach 5 Minuten erneut
• Bis zu 3 Wiederholungsversuche
• Nach allen fehlgeschlagenen Wiederholungsversuchen wird die Benachrichtigung verworfenNach dem Fehlschlagen aller Versuche wird die Benachrichtigung verworfen

Webhooks für eingehende SMS

Mit sms2mail exklusiv können eingehende SMS-Nachrichten an eine Webhook-URL statt per E-Mail weitergeleitet werden.

Anfrageformat

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.example.com
Content-Type: application/json

{
  "from": "+491711234567",
  "to": "+491512345678",
  "message": "The SMS text content",
  "timestamp": "2025-01-08T14:30:00Z"
}

Parameter

Implementierungsbeispiele

Python (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

# Webhook as delivery channel
@app.route('/webhook/message', methods=['POST'])
def message_webhook():
    data = request.get_json()

    print(f"Message from {data['from']}: {data['message']}")
    print(f"Team list: {data['account_email']}")

    # Process the message (create ticket, forward to Slack, etc.)
    # ...

    return jsonify({"status": "received"}), 200

# Delivery report webhook
@app.route('/webhook/delivery', methods=['POST'])
def delivery_webhook():
    status = request.form.get('status')
    reason = request.form.get('reason')
    to = request.form.get('to')
    msgid = request.form.get('msgid')

    if status == '0':
        print(f"Message {msgid} delivered to {to}")
    else:
        print(f"Message {msgid} failed: status={status}, reason={reason}")

    return 'OK', 200

PHP

<?php
// webhook_message.php - Webhook as delivery channel
$data = json_decode(file_get_contents('php://input'), true);

$from = $data['from'] ?? '';
$message = $data['message'] ?? '';
$account = $data['account_email'] ?? '';

error_log("Message from {$from} to {$account}: {$message}");

// Process the message
// ...

http_response_code(200);
echo json_encode(['status' => 'received']);

// ---

// webhook_delivery.php - Delivery reports
$status = $_POST['status'] ?? '';
$reason = $_POST['reason'] ?? '';
$to = $_POST['to'] ?? '';
$msgid = $_POST['msgid'] ?? '';

if ($status === '0') {
    error_log("Message {$msgid} delivered to {$to}");
} else {
    error_log("Message {$msgid} failed: status={$status}, reason={$reason}");
}

http_response_code(200);
echo "OK";

Node.js (Express)

const express = require('express');
const app = express();

app.use(express.urlencoded({ extended: true }));
app.use(express.json());

// Webhook as delivery channel
app.post('/webhook/message', (req, res) => {
    const { from, message, account_email, timestamp } = req.body;

    console.log(`Message from ${from}: ${message}`);
    console.log(`Team list: ${account_email}`);

    // Process the message
    // ...

    res.status(200).json({ status: 'received' });
});

// Delivery report webhook
app.post('/webhook/delivery', (req, res) => {
    const { status, reason, to, msgid } = req.body;

    if (status === '0') {
        console.log(`Message ${msgid} delivered to ${to}`);
    } else {
        console.log(`Message ${msgid} failed: status=${status}, reason=${reason}`);
    }

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

app.listen(3000);

Webhooks testen

Vor dem Produktiveinsatz: Testen Sie Ihre Webhook-Implementierung:

1. Nutzen Sie ein Test-Tool wie webhook.site oder ngrok, um eingehende Anfragen zu inspizierenVerwenden Sie ein Test-Tool wie webhook.site oder ngrok, um eingehende Anfragen zu prüfen
2. Fügen Sie die Test-URL als Webhook-Mitglied in Ihrer Teamliste hinzu
3. Testnachricht an die Teamliste senden
4. Überprüfen Sie, ob die Anfrage auf webhook.site mit korrektem JSON-Payload erscheint

Sicherheitshinweise

• Verwenden Sie HTTPS, um Webhook-Daten bei der Übertragung zu verschlüsselnVerwenden Sie HTTPS, um Webhook-Daten während der Übertragung zu verschlüsseln
• Fügen Sie Ihrer Webhook-URL einen geheimen Token zur Validierung hinzu (z.B. https://example.com/webhook?token=secret123)
• Verarbeiten Sie Webhooks asynchron, um Timeout-Probleme zu vermeiden
• Protokollieren Sie alle Webhook-Anfragen für Debugging und Audit
• Implementieren Sie Idempotenz – behandeln Sie doppelte Benachrichtigungen elegantImplementieren Sie Idempotenz – behandeln Sie doppelte Benachrichtigungen korrekt