Webhooks von Laravel an VtigerCRM senden: Schritt-für-Schritt-Integration

In diesem Artikel zeige ich, wie Sie Daten aus einem Laravel-Portal (z. B. Lead-Formulare) per Webhook an VtigerCRM senden – asynchron, robust und skalierbar. Sie lernen, wie Sie:

Custom Webhooks in VtigerCRM erstellen.
Queue-basierte Jobs in Laravel für zuverlässige Übertragungen nutzen.
Automatische Retries bei Fehlern implementieren.

Anwendungsfälle

Lead-Generierung: Erstellen Sie automatisch Leads in Vtiger, wenn ein Kunde ein Formular auf Ihrer Laravel-Website ausfüllt.
Bestellungen synchronisieren: Übertragen Sie E-Commerce-Daten in Echtzeit.
Fehlerbehandlung: Verhindern Sie Datenverluste bei Serverausfällen.

Voraussetzungen

Laravel 9+
VtigerCRM (On-Premise oder Cloud)
RabbitMQ (für Queues)
Pakete: spatie/data-transfer-object, lorisleiva/laravel-actions

Schritt 1: Webhook in VtigerCRM erstellen

1.1 ShortURL generieren

Erstellen Sie ein Skript (vtiger/scripts/create_leads_webhook.php):

<?php  
chdir('../');  
require_once 'include/utils/utils.php';  
require_once 'include/utils/VtlibUtils.php';  
require_once 'modules/Vtiger/helpers/ShortURL.php';  

global $adb;  
$adb = PearDatabase::getInstance();  

$options = [  
    'handler_path' => 'modules/Leads/handlers/LeadCreateTaskHandler.php',  
    'handler_class' => 'Leads_CreateTask_Handler',  
    'handler_function' => 'createLead',  
    'handler_data' => []  
];  

$trackURL = Vtiger_ShortURL_Helper::generateURL($options);  
var_dump($trackURL);

Rufen Sie das Skript auf, um eine **Webhook-URL** (z. B. `http://vtiger.test/shorturl.php?id=ABC123`) zu erhalten.

1.2 Handler implementieren

Erstellen Sie `modules/Leads/handlers/LeadCreateTaskHandler.php`:

class Leads_CreateTask_Handler {  
    public function createLead($data): void {  
        global $current_user;  
        $current_user->id = 1; // Admin-ID  

        $dataRequest = json_decode(file_get_contents('php://input'), true);  

        $leadModel = Vtiger_Record_Model::getCleanInstance('Leads');  
        $leadModel->set('mode', 'create');  
        $leadModel->set('lastname', $dataRequest['last_name']);  
        $leadModel->set('firstname', $dataRequest['first_name']);  
        $leadModel->set('email', $dataRequest['email']);  
        $leadModel->set('phone', $dataRequest['phone']);  
        $leadModel->set('description', $dataRequest['description']);  
        $leadModel->set('assigned_user_id', 1);  
        $leadModel->set('designation', $dataRequest['portal_id']); // Laravel Lead-ID  
        $leadModel->save();  

        $response = new Vtiger_Response();  
        $response->setResult(['success' => true]);  
        $response->emit();  
    }  
}

---

Schritt 2: Laravel-Integration

2.1 Migration & Modell

Migration (database/migrations/2023_01_01_create_leads_table.php):

Schema::create('leads', function (Blueprint $table) {  
    $table->id();  
    $table->string('first_name', 190);  
    $table->string('last_name', 190);  
    $table->string('email', 100);  
    $table->string('phone', 100);  
    $table->text('description')->nullable();  
    $table->timestamps();  
});

Modell (app/Models/Lead.php):

namespace App\Models;  
use Illuminate\Database\Eloquent\Model;  

class Lead extends Model {  
    protected $fillable = ['first_name', 'last_name', 'email', 'phone', 'description'];  
}

2.2 DTO & Action

Data Transfer Object (app/Transfers/LeadTransfer.php):

namespace App\Transfers;  
use Spatie\DataTransferObject\DataTransferObject;  

class LeadTransfer extends DataTransferObject {  
    public ?int $id;  
    public string $first_name;  
    public string $last_name;  
    public string $email;  
    public string $phone;  
    public string $description;  
}

Action (app/Actions/StoreLeadAction.php):

namespace App\Actions;  
use Lorisleiva\Actions\Concerns\AsAction;  
use App\Models\Lead;  
use App\Jobs\VtigerWebhookJob;  

class StoreLeadAction {  
    use AsAction;  

    public function handle(LeadTransfer $transfer) {  
        $lead = Lead::create($transfer->toArray());  
        $transfer->id = $lead->id;  
        VtigerWebhookJob::dispatch($transfer);  
        return $transfer;  
    }  
}

2.3 Job mit Retry-Logik

app/Jobs/VtigerWebhookJob.php:

namespace App\Jobs;  
use Illuminate\Support\Facades\Http;  
use Illuminate\Queue\SerializesModels;  

class VtigerWebhookJob implements ShouldQueue {  
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;  

    public int $tries = 0; // Unbegrenzte Versuche  

    public function __construct(protected LeadTransfer $leadTransfer) {}  

    public function handle() {  
        $data = $this->leadTransfer->toArray();  
        $data['portal_id'] = $this->leadTransfer->id;  

        $response = Http::timeout(5)  
            ->post(config('services.lead_webhook'), $data);  

        if ($response->failed()) {  
            $this->release(now()->addMinutes(15 * $this->attempts()));  
        }  
    }  

    public function retryUntil() {  
        return now()->addDay(); // Retry für 24h  
    }  

    public function failed(\Exception $e) {  
        \Log::error("Webhook fehlgeschlagen: " . $e->getMessage());  
    }  
}

---

Schritt 3: Konfiguration

1. Webhook-URL in `.env`:

LEAD_WEBHOOK=http://vtiger.test/shorturl.php?id=ABC123

2. Service-Provider (`config/services.php`):

'lead_webhook' => env('LEAD_WEBHOOK'),

Best Practices

Validierung: Nutzen Sie Laravel-Request-Klassen, um Eingaben zu prüfen.
Deduplizierung: Fügen Sie in Vtiger eine Logik hinzu, um Duplikate über designation (Laravel Lead-ID) zu erkennen.
Sicherheit:

HTTPS: Nutzen Sie verschlüsselte Verbindungen.
IP-Whitelisting: Beschränken Sie Webhook-Zugriffe auf Ihre Server-IPs.

Fehlerbehandlung

Retry-Mechanismus: Bei Fehlern wird der Job alle 15×n Minuten wiederholt (n = Anzahl der Fehlversuche).
Logging: Fehler werden in storage/logs/laravel.log erfasst.
Monitoring: Integrieren Sie Tools wie Laravel Horizon oder Sentry.

👉 GitHub-Beispielcode

Warum diese Architektur?

Entkopplung: Laravel und Vtiger laufen unabhängig voneinander.
Resilienz: Queues puffern Lastspitzen und Serverausfälle.
Skalierbarkeit: Horizontale Skalierung der Worker möglich.

Nächste Schritte:

Benachrichtigungen: Versenden Sie E-Mails an Sales-Teams bei neuen Leads.
Analytics: Tracken Sie Konversionsraten zwischen Laravel-Formularen und Vtiger-Deals.

Fragen? Stellen Sie sie in den Kommentaren – ich helfe gern! 🚀

„Mit Webhooks wird Ihre CRM-Integration zum Automaten – Daten fließen, als wären sie nie woanders gewesen.“

Entwickler, der außergewöhnliche CRM- und Laravel-Lösungen liefert