Sending webhooks | laravel-webhook-server | Spatie       

 SPATIE  

==

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-webhook-server](https://spatie.be/docs/laravel-webhook-server/v4)  Sending webhooks

 Version   v4      

 Other versions for crawler [v4](https://spatie.be/docs/laravel-webhook-server/v4) 

  Sending webhooks    
- [ Introduction ](https://spatie.be/docs/laravel-webhook-server/v4/introduction)
- [ Installation and setup ](https://spatie.be/docs/laravel-webhook-server/v4/installation-and-setup)
- [ Sending webhooks ](https://spatie.be/docs/laravel-webhook-server/v4/sending-webhooks)
- [ Signing requests ](https://spatie.be/docs/laravel-webhook-server/v4/signing-requests)
- [ Retrying failed webhooks ](https://spatie.be/docs/laravel-webhook-server/v4/retrying-failed-webhooks)
- [ Transport options ](https://spatie.be/docs/laravel-webhook-server/v4/transport-options)
- [ Events ](https://spatie.be/docs/laravel-webhook-server/v4/events)
- [ Testing webhooks ](https://spatie.be/docs/laravel-webhook-server/v4/testing-webhooks)
- [ Upgrading from v3 ](https://spatie.be/docs/laravel-webhook-server/v4/upgrading)

 Sending webhooks
================

###  On this page 

1. [ Send a JSON payload ](#content-send-a-json-payload)
2. [ Send synchronously or conditionally ](#content-send-synchronously-or-conditionally)
3. [ Change the HTTP verb and headers ](#content-change-the-http-verb-and-headers)
4. [ Send a raw body ](#content-send-a-raw-body)
5. [ Delivery IDs ](#content-delivery-ids)
6. [ Timestamps ](#content-timestamps)
7. [ Metadata and Horizon tags ](#content-metadata-and-horizon-tags)

Send a JSON payload
-----------------------------------------------------------------------------------------------------------------

```
use Spatie\WebhookServer\WebhookCall;

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

The payload is encoded once before dispatch using `JSON_THROW_ON_ERROR`. The package signs and sends those exact bytes on every attempt. Invalid JSON payloads throw `JsonException` at the dispatch call, including when signing is disabled.

Send synchronously or conditionally
-----------------------------------------------------------------------------------------------------------------------------------------------------------------

Use `dispatchSync()` to make the request immediately instead of putting it on the queue. Synchronous calls do not wait or loop through retries.

The methods `dispatchIf($condition)`, `dispatchUnless($condition)`, `dispatchSyncIf($condition)` and `dispatchSyncUnless($condition)` conditionally send a webhook.

Change the HTTP verb and headers
--------------------------------------------------------------------------------------------------------------------------------------------------------

The default verb is `post`, configured with `http_verb`. Override it with `useHttpVerb('put')`, or send a GET request with `useHttpVerb('get')`.

GET webhooks send the payload as query parameters and sign its JSON representation, not an empty body. Unsigned GET query parameters are not JSON-encoded.

Add default headers through the `headers` config key, or use `withHeaders()` for a single call:

```
WebhookCall::create()
    ->url('https://other-app.com/webhooks')
    ->payload(['key' => 'value'])
    ->useSecret('your-shared-secret')
    ->useHttpVerb('put')
    ->withHeaders(['X-Source' => 'billing'])
    ->dispatch();
```

Laravel HTTP global options and middleware apply to these requests. Global headers can be combined with webhook headers instead of replaced. Middleware that changes a signed body must also update its signature.

Send a raw body
-----------------------------------------------------------------------------------------------------

Use `sendRawBody()` instead of `payload()` to send XML, pre-encoded JSON, or another string. Raw bodies can be signed, including binary strings. Set a matching Content-Type for your receiver:

```
WebhookCall::create()
    ->url('https://other-app.com/webhooks')
    ->sendRawBody('someXMLContent')
    ->withHeaders(['Content-Type' => 'application/xml'])
    ->useSecret('your-shared-secret')
    ->dispatch();
```

Event payloads are strings for raw calls and arrays for JSON calls.

Delivery IDs
--------------------------------------------------------------------------------------------

Every request includes a `Webhook-Id` header containing the webhook UUID. It stays the same across retries. Retrieve it before dispatch with `getUuid()`, or set an application-specific ID using `uuid('your-delivery-id')`.

Set `webhook_id_header_name` to rename the header globally, or set it to `null` to disable it. Per call, use `withWebhookIdHeader('X-Delivery-Id')` or `withWebhookIdHeader(null)`. An explicitly supplied header with that name takes precedence, regardless of casing.

The default signer authenticates the body only, not the ID or other headers. A delivery ID is not replay protection: authenticate the request and make processing idempotent on the receiver.

Timestamps
--------------------------------------------------------------------------------------

Call `useTimestamp()` to include a `Timestamp` header containing the Unix timestamp for the attempt. Rename it using `timestamp_header_name` in the config file.

The default signer does not authenticate this header. For replay protection, put a timestamp in the signed payload and have the receiver validate its age.

Metadata and Horizon tags
-----------------------------------------------------------------------------------------------------------------------------------

Add local context with `meta(['order_id' => 123])`. Metadata is available to [event listeners](/docs/laravel-webhook-server/v4/events), but is not sent to the receiver.

Set Laravel Horizon tags using the `tags` config key or `withTags(['webhooks', 'billing'])`.

 A good
match?
-------------

### What we do best

- All things Laravel
- Custom frontend components
- Building APIs
- AI-powered features
- Simplifying things
- Clean solutions
- Integrating services

### Not our cup of tea

- WordPress themes
- Cutting corners
- Free mockups to win a job
- "Just execute the briefing"

 In short: we'd like to be a **substantial part** of your project.

 [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)
