Webhooks

MyWarranties supports webhooks for receiving external events, particularly for email processing.

Resend Inbound Email Webhook

Receive and process email replies to claim conversations.

Endpoint

POST /api/webhook/resend/inbound

How It Works

1. User receives email notification about a claim message
2. User replies directly to the email
3. Resend forwards the reply to our webhook
4. System extracts the reply and creates a new claim message

Email Address Format

Outbound emails use a reply-to address format:

claim+{claimId}@yourdomain.com

For example: claim+123@mywarranties.com

Webhook Payload

Resend sends the following payload:

{
  "type": "email.received",
  "data": {
    "id": "email_abc123",
    "from": "user@example.com",
    "to": ["claim+123@mywarranties.com"],
    "subject": "Re: New message about iPhone 15",
    "text": "Thanks for looking into this.\n\n> On Jan 15, 2024...",
    "html": "<p>Thanks for looking into this.</p>...",
    "headers": {
      "message-id": "<abc123@mail.example.com>",
      "in-reply-to": "<claim-123-message-5@mywarranties.com>"
    }
  }
}

Processing Logic

1. Extract Claim ID from the to address
2. Find User by the from email address
3. Extract Reply - strip quoted content and signatures
4. Create Message in the claim conversation
5. Notify the other party (customer or supplier)

Reply Extraction

The system intelligently extracts only the new reply content:

Thanks for looking into this!     ← Extracted as message

On Jan 15, 2024, Support wrote:  ← Stripped (quoted content)
> We'll investigate this issue.

--                               ← Stripped (signature)
John Doe

Webhook Security

Verify webhook authenticity using the signature header:

$signature = $request->headers->get('Resend-Signature');
$payload = $request->getContent();

$expectedSignature = hash_hmac('sha256', $payload, $webhookSecret);

if (!hash_equals($expectedSignature, $signature)) {
    throw new UnauthorizedException('Invalid signature');
}

Configuration

# Resend webhook secret for signature verification
RESEND_WEBHOOK_SECRET=whsec_your_secret_here

Setting Up Resend Webhooks

1. Log in to your Resend Dashboard
2. Create a new webhook endpoint
3. Set the URL to https://yourdomain.com/api/webhook/resend/inbound
4. Select the email.received event
5. Copy the webhook secret to your .env

Mercure (Outbound Real-time)

While not technically a webhook, Mercure provides real-time outbound events.

Topics

Topic Pattern	Description
claims/{id}/messages	New messages and read status
claims/{id}/status	Claim status updates

Subscribing

const url = new URL(process.env.MERCURE_PUBLIC_URL);
url.searchParams.append('topic', `claims/${claimId}/messages`);

const eventSource = new EventSource(url, {
  withCredentials: true
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Event Payloads

New Message:

{
  "type": "new_message",
  "message": {
    "id": "123",
    "senderId": "5",
    "senderName": "John Doe",
    "message": "Hello!",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Messages Read:

{
  "type": "messages_read",
  "messageIds": ["1", "2", "3"],
  "readAt": "2024-01-15T10:35:00Z"
}

Status Update:

{
  "type": "status_update",
  "claimId": 123,
  "status": "in_progress",
  "updatedAt": "2024-01-15T10:40:00Z"
}

Error Handling

Webhook endpoints return appropriate HTTP status codes:

Code	Meaning
200	Successfully processed
400	Invalid payload
401	Invalid signature
404	Claim or user not found
500	Internal error (will be retried)

Retry Logic

Resend automatically retries failed webhooks with exponential backoff. Return 5xx for temporary errors to trigger retries.