Sign up

Webhooks

Check that an event is from Goomzo, and manage your endpoints.

Webhook::verify checks an event's signature and timestamp, and returns the event. See Signatures.

Requirements

  • An endpoint, and its signing secret, which starts with whsec_. See Webhooks.

Receive an event

Pass the body exactly as it arrived, before decoding it:

Plain PHP
use Goomzo\Exception\WebhookVerificationException;
use Goomzo\Webhook;

try {
    $event = Webhook::verify(file_get_contents('php://input'), getallheaders(), getenv('GOOMZO_WEBHOOK_SECRET'));
} catch (WebhookVerificationException) {
    http_response_code(400);
    exit;
}
if ($event['type'] === 'message.delivered') {
    markDelivered($event['data']['id']);
}
http_response_code(204);
Laravel
use Goomzo\Exception\WebhookVerificationException;
use Goomzo\Webhook;
use Illuminate\Http\Request;

Route::post('/webhooks/goomzo', function (Request $request) {
    try {
        $event = Webhook::verify($request->getContent(), $request->headers->all(), config('services.goomzo.webhook_secret'));
    } catch (WebhookVerificationException) {
        abort(400);
    }
    // …
    return response()->noContent();
});

Important: Don't decode the body before checking it. The signature is of the body as it arrived. In Laravel, leave the route out of CSRF protection.

Manage endpoints

$endpoint = $goomzo->webhookEndpoints->create([
    'url' => 'https://example.com/webhooks/goomzo',
    'events' => ['message.delivered', 'message.failed'],
]);
$endpoint['secret']; // whsec_…
MethodDoes
webhookEndpoints->list()Lists your endpoints.
webhookEndpoints->get($id)Gets one.
webhookEndpoints->update($id, $changes)Changes an endpoint, or turns it off.
webhookEndpoints->delete($id)Deletes one.

Next steps

Last updated