Skip to main content

​
Overview

This page explains how Hypersender handles incoming WhatsApp webhooks, the default job that processes them, and how to register your own job class.

​
How it works

1

Route

The incoming webhook hits your app on the route configured at hypersender-config.whatsapp_webhook_route (default: whatsapp/webhook).
2

Controller

Hypersender\Http\Controllers\WhatsappWebhookController resolves the job class from config and dispatches it:
  • Config key: hypersender-config.whatsapp_webhook_job
  • The controller validates:
    • The class exists and is a string
    • The class implements Hypersender\Contracts\WhatsappWebhookJobInterface
  • The controller dispatches the job with two named arguments:
    • payload: $request->payload()
    • secret: $request->secret()
Because the controller uses named arguments, your job’s constructor must accept parameters named payload and secret.

​
The default job

Out of the box, the package ships with Hypersender\Jobs\ProcessWhatsappWebhookJob, which implements the interface Hypersender\Contracts\WhatsappWebhookJobInterface.

​
Key details

1

Constructor signature

public function __construct(
    public array $payload,
    public ?string $secret = null
) { }
2

Queue routing

If hypersender-config.whatsapp_queue is set, the job is queued there.
3

Handling

Validates the event field and dispatches an application event via WhatsappWebhookEventEnum mapping.

​
Using your own job class

You can replace the default job with your own implementation. Follow these steps:
1

Implement the interface

Your job must implement Hypersender\Contracts\WhatsappWebhookJobInterface (a marker interface). This is enforced by the controller.
2

Match the constructor names

Your job’s constructor must accept the same named parameters that the controller provides:
use Hypersender\Contracts\WhatsappWebhookJobInterface;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

namespace App\Jobs;

class MyWhatsappWebhookJob implements ShouldQueue, WhatsappWebhookJobInterface
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public array $payload, public ?string $secret = null)
    {
        // Optional: route to a specific queue
        if ($queue = config('hypersender-config.whatsapp_queue')) {
            $this->onQueue($queue);
        }
    }

    public function handle(): void
    {
        // Your custom processing logic here
        // $this->payload contains the webhook body
        // $this->secret contains the Authorization secret (if sent)
    }
}
3

Register your job class

You can register it either in your config or via environment variable.
  • Via .env:
HYPERSENDER_WHATSAPP_WEBHOOK_JOB=App\Jobs\MyWhatsappWebhookJob
  • Or by publishing/editing the config config/hypersender-config.php:
'whatsapp_webhook_job' => env('HYPERSENDER_WHATSAPP_WEBHOOK_JOB', App\Jobs\MyWhatsappWebhookJob::class),
Make sure the class is autoloadable and available to your app (e.g., in app/Jobs).

​
Can I use my own interface?

Yes! your job class can implement any additional interfaces you want for your own architecture. However, the package still requires your job to implement Hypersender\\Contracts\\WhatsappWebhookJobInterface because the controller enforces this at runtime. Swapping out that required interface via configuration is not supported. If you need to enforce your own contract, simply implement both interfaces on your job class.
  • API key: HYPERSENDER_WHATSAPP_API_KEY
  • Instance ID: HYPERSENDER_WHATSAPP_INSTANCE_ID
  • Webhook Authorization secret: HYPERSENDER_WHATSAPP_WEBHOOK_AUTHORIZATION_SECRET
  • Webhook route: HYPERSENDER_WHATSAPP_WEBHOOK_ROUTE (defaults to whatsapp/webhook)
  • Webhook job: HYPERSENDER_WHATSAPP_WEBHOOK_JOB (defaults to Hypersender\Jobs\ProcessWhatsappWebhookJob)
  • Queue name: HYPERSENDER_WHATSAPP_QUEUE (defaults to default)

​
Validation rules enforced by the controller

If the configured job class is invalid, the controller aborts the request with HTTP 500:
  • Not a string or class does not exist
  • Does not implement Hypersender\Contracts\WhatsappWebhookJobInterface

​
Payload expectations

The default job expects an event string at payload['event']. If it is missing or not a string, the default job will report and fail the job. If you write a custom job, you can apply your own validation.

​
Quick checklist

  • Custom job implements Hypersender\Contracts\WhatsappWebhookJobInterface
  • Constructor signature matches the named args: __construct(array $payload, ?string $secret = null)
  • HYPERSENDER_WHATSAPP_WEBHOOK_JOB is set (or config updated)
  • Optional: set HYPERSENDER_WHATSAPP_QUEUE to route jobs to a specific queue

​
Troubleshooting

  • 500 error on webhook: Ensure the configured job class exists and implements WhatsappWebhookJobInterface.
  • Constructor argument mismatch: Because dispatch uses named args, your constructor parameter names must be exactly payload and secret.
  • Queue not used: Verify HYPERSENDER_WHATSAPP_QUEUE (or config) and that your job calls $this->onQueue(...) in the constructor (or elsewhere) if you want to force a specific queue.

​
TL;DR

  • Default job: Hypersender\Jobs\ProcessWhatsappWebhookJob implements Hypersender\Contracts\WhatsappWebhookJobInterface and is used by default.
  • Bring your own: Create a job that implements the interface, accepts payload and secret in the constructor, and register it via HYPERSENDER_WHATSAPP_WEBHOOK_JOB or in config/hypersender-config.php.
⌘I