## Webhooks

Webhooks let you receive real-time notifications when messages are sent or received. Configure webhooks from within the Project Blue dashboard alongside your API keys.

### Configuration

In the Project Blue app, you can:

- Paste the webhook URL you want to receive events at
- Toggle whether the webhook fires for outbound messages, inbound messages, or both
- Send test payloads to verify your endpoint is working

![Webhook configuration in the Project Blue dashboard](https://api.tryprojectblue.com/pb-app/pb_webhook.png)

### Delivery

Your endpoint should answer `2xx`. Anything else — including a network error or a timeout — counts as a failure.

**There are no retries.** Each event is delivered exactly once; a failed delivery is not queued or replayed, so a webhook is not a durable log. Reconcile with [`/get-messages-api`](https://api.tryprojectblue.com/#list-messages) if you need guaranteed coverage.

After **20 consecutive failures** the webhook is automatically disabled. The counter resets on the first success. Today that happens silently — there is no email and no dashboard banner, so check the Webhooks tab if events stop arriving.

### Webhook payload

The `direction` field indicates whether the message was inbound or outbound.

- `message` (string, required) — The text content of the message.

- `destination` (string, required) — The phone number the message was sent to, in E.164 format.

- `receivedAt` (string, required) — ISO 8601 timestamp of when the message was received.

- `direction` (string, required) — Either "inbound" or "outbound", based on message direction.

- `messageId` (number, required) — Unique numeric identifier for the message.

- `guid` (string, required) — Globally unique message identifier.

- `linePhoneNumber` (string, required) — The Project Blue line phone number associated with this message.

> **HubSpot accounts receive a wider payload**
>
> On accounts whose webhooks are configured through the HubSpot variant of the Webhooks tab, every field above is still present, plus `contactPhoneNumber`, `dateReceived` (a legacy alias for `receivedAt`), `hubspotContactId` (number), and `hubspotContactIdText` (the same id as a string). Those webhooks have no inbound/outbound toggles and are not covered by the auto-disable behaviour described above.

**Payload — Inbound**

```json
{
  "message": "Yes, I'm interested! When can we schedule?",
  "destination": "+15551234567",
  "receivedAt": "2026-03-04T18:30:00.000Z",
  "direction": "inbound",
  "messageId": 456,
  "guid": "sample-guid-1234",
  "linePhoneNumber": "+15559876543"
}
```

**Payload — Outbound**

```json
{
  "message": "Great! Let's book you in for Thursday at 2pm.",
  "destination": "+15551234567",
  "receivedAt": "2026-03-04T18:31:00.000Z",
  "direction": "outbound",
  "messageId": 789,
  "guid": "sample-guid-5678",
  "linePhoneNumber": "+15559876543"
}
```