laravel-webhook-server：从Laravel应用发送webhook

# Send webhooks from Laravel apps [](https://packagist.org/packages/spatie/laravel-webhook-server)  [](https://packagist.org/packages/spatie/laravel-webhook-server) 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 for [signing calls](https://github.com/spatie/laravel-webhook-server#how-signing-requests-works), [retrying calls and backoff strategies](https://github.com/spatie/laravel-webhook-server#retrying-failed-webhooks). If you need to receive and process webhooks take a look at our [laravel-webhook-client](https://github.com/spatie/laravel-webhook-client) package. ## Support us [<img src="https://github-ads.s3.eu-central-1.amazonaws.com/laravel-webhook-server.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/laravel-webhook-server) We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). 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 on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). ## Installation You can install the package via composer: ```bash composer require spatie/laravel-webhook-server ``` You can publish the config file with: ```bash php artisan vendor:publish --provider="Spatie\WebhookServer\WebhookServerServiceProvider" ``` This is the contents of the file that will be published at `config/webhook-server.php`: ```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 that 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, /* * By default we will verify that the ssl certificate of the destination * of the webhook is valid. */ 'verify_ssl' => true, ]; ``` By default, the package uses queues to retry failed webhook requests. Be sure to set up a real queue other than `sync` in non-local environments. ## Usage This is the simplest way to call a webhook: ```php WebhookCall::create() ->url('https://other-app.com/webhooks') ->payload(['key' => 'value']) ->useSecret('sign-using-this-secret') ->dispatch(); ``` This will send a post request to `https://other-app.com/webhooks`. The body of the request will be JSON encoded version of the array passed to `payload`. The request will have a header called `Signature` that will contain a signature the receiving app can use [to verify](https://github.com/spatie/laravel-webhook-server#how-signing-requests-works) the payload hasn't been tampered with. If the receiving app doesn't respond with a response code starting with `2`, 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, the `FinalWebhookCallFailedEvent` will be raised. ### Send webhook synchronously If you would like to call the webhook immediately (synchronously), you may use the dispatchNow method. When using this method, the webhook will not be queued and will be run immediately. This can be helpfull in situation where sending the webhook is part of a bigger job that already has been queued. ```php WebhookCall::create() ... ->dispatchNow(); ``` ### How signing requests works 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 with `Illuminate\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 called `Signature` that will contain a signature the receiving app can use the payload hasn't been tampered with. This is how that signature is calculated: ```php // 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); ``` ### Skip signing request We don't recommend this, but if you don't want the web hook request to be signed call the `doNotSign` method. ```php WebhookCall::create() ->doNotSign() ... ``` By calling this method, the `Signature` header will not be set. ### Customizing signing requests If you want to customize the signing process, you can create your own custom signer. A signer is any class that implements `Spatie\WebhookServer\Signer`. This is what that interface looks like. ```php namespace Spatie\WebhookServer\Signer; interface Signer { public function signatureHeaderName(): string; public function calculateSignature(array $payload, string $secret): string; } ``` After creating your signer, you can specify it's class name in the `signer` key of the `webhook-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: ```php 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 the `signature_header_name` in the `webhook-server` config file. ### Retrying failed webhooks When the app to which we're sending the webhook fails to send a response with a `2xx` 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 the `timeout_in_seconds` key of the `webhook-server` config file. Alternatively, you can override the timeout for a specific webhook like this: ```php 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 the `tries` key of the config file. Alternatively, you can specify the number of tries for a specific webhook like this: ```php WebhookCall::create() ->maximumTries(5) ... ->dispatch(); ``` To not hammer the remote app we'll wait some time between each attempt. By d