From df480d8bc3ebe8de4c6785a44f3048c3bc805c29 Mon Sep 17 00:00:00 2001 From: Freek Van der Herten Date: Fri, 14 Jun 2019 13:45:11 +0200 Subject: [PATCH 1/4] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c87fb33..ad90d2a 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ This is the simplest way to call a webhook: Webhook::create() ->url('https://other-app.com/webhooks') ->payload(['key' => 'value']) - ->signUsingSecret('sign-using-this-secret') + ->useSecret('sign-using-this-secret') ->call(); ``` From 9df485e428c704af1fa9bec1bf39a810aa8d89bb Mon Sep 17 00:00:00 2001 From: Freek Van der Herten Date: Fri, 14 Jun 2019 16:30:15 +0200 Subject: [PATCH 2/4] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32ba41b..4c5d7da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,6 @@ All notable changes to `laravel-webhook-server` will be documented in this file -## 1.0.0 - 201X-XX-XX +## 1.0.0 - 2019-06-14 - initial release From 0bedbccf7b1c9e39564dd7f5fcd41abafcfc5380 Mon Sep 17 00:00:00 2001 From: Freek Van der Herten Date: Fri, 14 Jun 2019 16:33:40 +0200 Subject: [PATCH 3/4] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ad90d2a..e8013d7 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ If the receiving app doesn't respond with a response code starting with `2`, the ### How signing requests works -When setting up it's common to generate, store and share a secret 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 really entirely up to you. The package will use the secret to sign a webhook call. +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 really 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. From 7fc479e8376e344cc8bdc61abc0b0ab88bcbaaf3 Mon Sep 17 00:00:00 2001 From: Freek Van der Herten Date: Fri, 14 Jun 2019 16:39:02 +0200 Subject: [PATCH 4/4] Update README.md --- README.md | 56 +++++++++++++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index e8013d7..21eb188 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ [![Quality Score](https://img.shields.io/scrutinizer/g/spatie/laravel-webhook-server.svg?style=flat-square)](https://scrutinizer-ci.com/g/spatie/laravel-webhook-server) [![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-webhook-server.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-webhook-server) -A webhook is a way for an app to provide information to another app about a certain event. The way the two apps communicate is with a simple HTTP request. +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 easily configure and send webhooks in a Laravel app. 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). +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. @@ -80,7 +80,7 @@ return [ ]; ``` -By default the package uses queues to retry failed webhook requests. Be sure to setup a real queue other than `sync` in non-local environments. +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 @@ -94,15 +94,15 @@ Webhook::create() ->call(); ``` -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. +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. +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. ### 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 really entirely up to you. The package will use the secret to sign a webhook call. +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. +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 @@ -115,7 +115,7 @@ $signature = hash_hmac('sha256', $payloadJson, $secret); ### 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`. +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. @@ -130,9 +130,9 @@ interface Signer } ``` -After creating your signer you can specify it's class name in the `signer` key of the `webhook-server` config file. Your signer will than be used by default in all webhook calls. +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 +You can also specify a signer for a specific webhook call: ```php Webhook::create() @@ -141,13 +141,13 @@ Webhook::create() ->call(); ``` -If you just want to customize the name of the header you don't need to use a custom signer, but you can just change the value in the `signature_header_name` in the `webhook-server` config file. +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: +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 Webhook::create() @@ -156,7 +156,7 @@ Webhook::create() ->call(); ``` -When a webhook call fails we'll retry the call two more times. You can set the default amount of times we just retry the webhook call in the `tries` key of the config file. Alternatively, you can specify the amount of tries for a specific webhook like this: +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 Webhook::create() @@ -165,7 +165,7 @@ Webhook::create() ->call(); ``` -To not hammer the remote app we'll wait some time between each attempts. By default we wait 10 seconds between the first and second attempt, 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 behaviour is implemented in the default `ExponentialBackoffStrategy`. +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 attempt, 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 default `ExponentialBackoffStrategy`. You can define your own backoff strategy by creating a class that implements `Spatie\WebhookServer\BackoffStrategy\BackoffStrategy`. This is what that interface looks like: @@ -178,7 +178,7 @@ interface BackoffStrategy } ``` -You can make your custom strategy the default strategy by specifying it's fully qualified classname in the `backoff_strategy` of the `webhook-server` config file. Alternatively you can specify a strategy for a specific webhook like this. +You can make your custom strategy the default strategy by specifying it's fully qualified class name in the `backoff_strategy` of the `webhook-server` config file. Alternatively, you can specify a strategy for a specific webhook like this. ```php Webhook::create() @@ -187,14 +187,14 @@ Webhook::create() ->call(); ``` -Under the hood the retrying of the webhook calls is implemented using [delayed dispatching](https://laravel.com/docs/master/queues#delayed-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 away so there is more than 15 minutes between each attempt. +Under the hood, the retrying of the webhook calls is implemented using [delayed dispatching](https://laravel.com/docs/master/queues#delayed-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. -### Customizing the http verb +### Customizing the HTTP verb -By default all webhooks will use the `post` method. You can customize that by specify the http verb you want in the `http_verb` key of the `webhook-server` config file. +By default, all webhooks will use the `post` method. You can customize that by specifying the HTTP verb you want in the `http_verb` key of the `webhook-server` config file. -You can also override the default for a specific call by use the `useHttpVerb` method. +You can also override the default for a specific call by using the `useHttpVerb` method. ```php Webhook::create() @@ -205,7 +205,7 @@ Webhook::create() ### Adding extra headers -You can extra headers by adding the to the `headers` key in the `webhook-server` config file. If you want to add extra headers for a specific webhook you can use the `withHeaders` call. +You can use extra headers by adding them to the `headers` key in the `webhook-server` config file. If you want to add additional headers for a specific webhook, you can use the `withHeaders` call. ```php Webhook::create() @@ -218,7 +218,7 @@ Webhook::create() ### Verifying the SSL certificate of the receiving app -When using an url that starts with `https://` 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 the `verify_ssl` key in the `webhook-server` config file to `false`. +When using an URL that starts with `https://` 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 the `verify_ssl` key in the `webhook-server` config file to `false`. You can also disable the verification per webhook call with the `doNotVerifySsl` method. @@ -231,7 +231,7 @@ Webhook::create() ### Adding meta information -You can add extra meta information to the webhook. This meta information will not be transmitted, it will only be used to pass to [the events this package fires](#events). +You can add extra meta information to the webhook. This meta information will not be transmitted, and it will only be used to pass to [the events this package fires](#events). This is how you can add meta information: @@ -244,7 +244,7 @@ Webhook::create() ### Adding tags -If you're using [Laravel Horizon](https://laravel.com/docs/5.8/horizon) for your queues you'll be happy to know that we support [tags](https://laravel.com/docs/5.8/horizon#tags). +If you're using [Laravel Horizon](https://laravel.com/docs/5.8/horizon) for your queues, you'll be happy to know that we support [tags](https://laravel.com/docs/5.8/horizon#tags). To add tags to the underlying job that'll perform the webhook call, simply specify them in the `tags` key of the `webhook-server` config file or use the `withTags` method: @@ -259,13 +259,13 @@ Webhook::create() The package fires these events: - `WebhookCallSucceededEvent`: the remote app responded with a `2xx` response code. -- `WebhookCallFailedEvent`: the remote app responded with a non `2xx` response code or it did not respond at all +- `WebhookCallFailedEvent`: the remote app responded with a non `2xx` response code, or it did not respond at all - `FinalWebhookCalledFailedEvent`: 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 +- `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 with [the `meta` call](#adding-meta-information) @@ -289,11 +289,11 @@ Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ### Security -If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker. +If you discover any security-related issues, please email freek@spatie.be instead of using the issue tracker. ## Postcardware -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. +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, Samberstraat 69D, 2060 Antwerp, Belgium. @@ -306,7 +306,7 @@ We publish all received postcards [on our company website](https://spatie.be/en/ ## Support us -Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource). +Spatie is a web design agency based in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource). Does your business depend on our contributions? Reach out and support us on [Patreon](https://www.patreon.com/spatie). All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.