Repository files navigation

Send webhooks from Laravel apps

A webhook is a way for an app to provide information to another app about a particular event. The way the two apps communicate is with a simple HTTP request.

This package allows you to configure and send webhooks in a Laravel app easily. It has support forsigning calls,retrying calls and backoff strategies.

If you need to receive and process webhooks take a look at ourlaravel-webhook-client package.

We invest a lot of resources into creatingbest in class open source packages. You can support us bybuying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address onour contact page. We publish all received postcards onour virtual postcard wall.

You can install the package via composer:

composer require spatie/laravel-webhook-server

You can publish the config file with:

php artisan vendor:publish --provider="Spatie\WebhookServer\WebhookServerServiceProvider"

This is the contents of the file that will be published atconfig/webhook-server.php:

return [/*     *  The default queue that should be used to send webhook requests.     */'queue' =>'default',/*     * The default http verb to use.     */'http_verb' =>'post',/*     * This class is responsible for calculating the signature that will be added to     * the headers of the webhook request. A webhook client can use the signature     * to verify the request hasn't been tampered with.     */'signer' => \Spatie\WebhookServer\Signer\DefaultSigner::class,/*     * This is the name of the header where the signature will be added.     */'signature_header_name' =>'Signature',/*     * These are the headers that will be added to all webhook requests.     */'headers' => [],/*     * If a call to a webhook takes longer this amount of seconds     * the attempt will be considered failed.     */'timeout_in_seconds' =>3,/*     * The amount of times the webhook should be called before we give up.     */'tries' =>3,/*     * This class determines how many seconds there should be between attempts.     */'backoff_strategy' => \Spatie\WebhookServer\BackoffStrategy\ExponentialBackoffStrategy::class,/*     * This class is used to dispatch webhooks onto the queue.     */'webhook_job' => \Spatie\WebhookServer\CallWebhookJob::class,/*     * By default we will verify that the ssl certificate of the destination     * of the webhook is valid.     */'verify_ssl' =>true,/*     * When set to true, an exception will be thrown when the last attempt fails     */'throw_exception_on_failure' =>false,/*     * When using Laravel Horizon you can specify tags that should be used on the     * underlying job that performs the webhook request.     */'tags' => [],];

By default, the package uses queues to retry failed webhook requests. Be sure to set up a real queue other thansync in non-local environments.

This is the simplest way to call a webhook:

WebhookCall::create()   ->url('https://other-app.com/webhooks')   ->payload(['key' =>'value'])   ->useSecret('sign-using-this-secret')   ->dispatch();

This will send a post request tohttps://other-app.com/webhooks. The body of the request will be JSON encoded version of the array passed topayload. The request will have a header calledSignature that will contain a signature the receiving app can useto verify the payload hasn't been tampered with. Dispatching a webhook call will also fire aDispatchingWebhookCallEvent.

If the receiving app doesn't respond with a response code starting with2, the package will retry calling the webhook after 10 seconds. If that second attempt fails, the package will attempt to call the webhook a final time after 100 seconds. Should that attempt fail, theFinalWebhookCallFailedEvent will be raised.

If you would like to call the webhook immediately (synchronously), you may use the dispatchSync method. When using this method, the webhook will not be queued and will be run immediately. This can be helpful in situations where sending the webhook is part of a bigger job that already has been queued.

WebhookCall::create()   ...   ->dispatchSync();

If you would like to conditionally dispatch a webhook, you may use thedispatchIf,dispatchUnless,dispatchSyncIf, anddispatchSyncUnless methods:

WebhookCall::create()   ...   ->dispatchIf($condition);WebhookCall::create()   ...   ->dispatchUnless($condition);WebhookCall::create()   ...   ->dispatchSyncIf($condition);WebhookCall::create()   ...   ->dispatchSyncUnless($condition);

When setting up, it's common to generate, store, and share a secret between your app and the app that wants to receive webhooks. Generating the secret could be done withIlluminate\Support\Str::random(), but it's entirely up to you. The package will use the secret to sign a webhook call.

By default, the package will add a header calledSignature that will contain a signature the receiving app can use if the payload hasn't been tampered with. This is how that signature is calculated:

// payload is the array passed to the `payload` method of the webhook// secret is the string given to the `signUsingSecret` method on the webhook.$payloadJson =json_encode($payload);$signature =hash_hmac('sha256',$payloadJson,$secret);

We don't recommend this, but if you don't want the webhook request to be signed call thedoNotSign method.

WebhookCall::create()   ->doNotSign()    ...

By calling this method, theSignature header will not be set.

If you want to customize the signing process, you can create your own custom signer. A signer is any class that implementsSpatie\WebhookServer\Signer.

This is what that interface looks like.

namespaceSpatie\WebhookServer\Signer;interface Signer{publicfunctionsignatureHeaderName():string;publicfunctioncalculateSignature(array$payload,string$secret):string;}

After creating your signer, you can specify its class name in thesigner key of thewebhook-server config file. Your signer will then be used by default in all webhook calls.

You can also specify a signer for a specific webhook call:

WebhookCall::create()    ->signUsing(YourCustomSigner::class)    ...    ->dispatch();

If you want to customize the name of the header, you don't need to use a custom signer, but you can change the value in thesignature_header_name in thewebhook-server config file.

When the app to which we're sending the webhook fails to send a response with a2xx status code the package will consider the call as failed. The call will also be considered failed if the remote app doesn't respond within 3 seconds.

You can configure that default timeout in thetimeout_in_seconds key of thewebhook-server config file. Alternatively, you can override the timeout for a specific webhook like this:

WebhookCall::create()    ->timeoutInSeconds(5)    ...    ->dispatch();

When a webhook call fails, we'll retry the call two more times. You can set the default amount of times we retry the webhook call in thetries key of the config file. Alternatively, you can specify the number of tries for a specific webhook like this:

WebhookCall::create()    ->maximumTries(5)    ...    ->dispatch();

To not hammer the remote app we'll wait some time between each attempt. By default, we wait 10 seconds between the first and second attempts, 100 seconds between the third and the fourth, 1000 between the fourth and the fifth, and so on. The maximum amount of seconds that we'll wait is 100 000, which is about 27 hours. This behavior is implemented in the defaultExponentialBackoffStrategy.

You can define your own backoff strategy by creating a class that implementsSpatie\WebhookServer\BackoffStrategy\BackoffStrategy. This is what that interface looks like:

namespaceSpatie\WebhookServer\BackoffStrategy;interface BackoffStrategy{publicfunctionwaitInSecondsAfterAttempt(int$attempt):int;}

You can make your custom strategy the default strategy by specifying its fully qualified class name in thebackoff_strategy of thewebhook-server config file. Alternatively, you can specify a strategy for a specific webhook like this.

WebhookCall::create()    ->useBackoffStrategy(YourBackoffStrategy::class)    ...    ->dispatch();

Under the hood, the retrying of the webhook calls is implemented usingdelayed dispatching. Amazon SQS only has support for a small maximum delay. If you're using Amazon SQS for your queues, make sure you do not configure the package in a way so there are more than 15 minutes between each attempt.

By default, all webhooks will use thepost method. You can customize that by specifying the HTTP verb you want in thehttp_verb key of thewebhook-server config file.

You can also override the default for a specific call by using theuseHttpVerb method.

WebhookCall::create()    ->useHttpVerb('get')    ...    ->dispatch();

You can use extra headers by adding them to theheaders key in thewebhook-server config file. If you want to add additional headers for a specific webhook, you can use thewithHeaders call.

WebhookCall::create()    ->withHeaders(['Another Header' =>'Value of Another Header'    ])    ...    ->dispatch();

You can direct webhooks through a proxy by specifying theproxy key in thewebhook-server config file. To set a proxy for a specificrequest, you can use theuseProxy call.

WebhookCall::create()    ->useProxy('http://proxy.server:3128')    ...

To safeguard the integrity of webhook data transmission, it's critical to authenticate the intended recipient of your webhook payload.Mutual TLS authentication serves as a robust method for this purpose. Contrary to standard TLS, where only the client verifies the server,mutual TLS requires both the webhook endpoint (acting as the client) and the webhook provider (acting as the server) to authenticate each other.This is achieved through an exchange of certificates during the TLS handshake, ensuring that both parties confirm each other's identity.

Note: If you need to include your own certificate authority, pass the certificate path to theverifySsl() method.

WebhookCall::create()    ->mutualTls(        certPath:storage_path('path/to/cert.pem'),         certPassphrase:'optional_cert_passphrase',         sslKeyPath:storage_path('path/to/key.pem'),         sslKeyPassphrase:'optional_key_passphrase'    )

The proxy specification follows theguzzlehttp proxy format

When using a URL that starts withhttps:// the package will verify if the SSL certificate of the receiving party is valid. If it is not, we will consider the webhook call failed. We don't recommend this, but you can turn off this verification by setting theverify_ssl key in thewebhook-server config file tofalse.

You can also disable the verification per webhook call with thedoNotVerifySsl method.

WebhookCall::create()    ->doNotVerifySsl()    ...    ->dispatch();

You can add extra meta information to the webhook. This meta information will not be transmitted, and it will only be used to pass tothe events this package fires.

This is how you can add meta information:

WebhookCall::create()    ->meta($arrayWithMetaInformation)    ...    ->dispatch();

If you're usingLaravel Horizon for your queues, you'll be happy to know that we supporttags.

To add tags to the underlying job that'll perform the webhook call, simply specify them in thetags key of thewebhook-server config file or use thewithTags method:

WebhookCall::create()    ->withTags($tags)    ...    ->dispatch();

By default, the package will not log any exceptions that are thrown when sending a webhook.

To handle exceptions you need to create listeners for theSpatie\WebhookServer\Events\WebhookCallFailedEvent and/orSpatie\WebhookServer\Events\FinalWebhookCallFailedEvent events.

By default, failing jobs will be ignored. To throw an exception when the last attempt of a job fails, you can callthrowExceptionOnFailure :

WebhookCall::create()    ->throwExceptionOnFailure()    ...    ->dispatch();

or activate thethrow_exception_on_failure global option of thewebhook-server config file.

By default, all webhooks will transform the payload into JSON. Instead of sending JSON, you can send any string by using thesendRawBody(string $body) option instead.

Due to a type mismatch in the Signer API, it is currently not supported to sign raw data requests.When using thesendRawBody option, you will receive astring payload in the WebhookEvents.

WebhookCall::create()    ->sendRawBody("<root>someXMLContent</root>")    ->doNotSign()    ...    ->dispatch();

The package fires these events:

• DispatchingWebhookCallEvent: right before the webhook call will be dispatched to the queue.
• WebhookCallSucceededEvent: the remote app responded with a2xx response code.
• WebhookCallFailedEvent: the remote app responded with a non2xx response code, or it did not respond at all.
• FinalWebhookCallFailedEvent: the final attempt to call the webhook failed.

All these events have these properties:

• httpVerb: the verb used to perform the request
• webhookUrl: the URL to where the request was sent
• payload: the used payload
• headers: the headers that were sent. This array includes the signature header
• meta: the array of values passed to the webhook withthemeta call
• tags: the array oftags used
• uuid: a unique string to identify this call. This uuid will be the same for all attempts of a webhook call.

Except for theDispatchingWebhookCallEvent, all events have these additional properties:

• attempt: the attempt number
• response: the response returned by the remote app. Can be an instance of\GuzzleHttp\Psr7\Response ornull.

composertest

When using the package in automated tests, you'll want to perform one of the following to ensure that no webhooks are sent out to genuine websites

useIlluminate\Support\Facades\Bus;useSpatie\WebhookServer\CallWebhookJob;useTests\TestCase;class TestFileextends TestCase{publicfunctiontestJobIsDispatched()    {        Bus::fake();... Perform webhook call ...        Bus::assertDispatched(CallWebhookJob::class);    }}

useIlluminate\Support\Facades\Queue;useSpatie\WebhookServer\CallWebhookJob;useTests\TestCase;class TestFileextends TestCase{publicfunctiontestJobIsQueued()    {        Queue::fake();... Perform webhook call ...        Queue::assertPushed(CallWebhookJob::class);    }}

Please seeCHANGELOG for more information on what has changed recently.

Please seeCONTRIBUTING for details.

If you discover any security-related issues, please emailfreek@spatie.be instead of using the issue tracker.

You're free to use this package, but if it makes it to your production environment, we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium.

We publish all received postcardson our company website.

• Freek Van der Herten
• All Contributors

The MIT License (MIT). Please seeLicense File for more information.