Webhooks
PRO AGENTWebhooks notify your server when emails arrive at a Blip inbox. Instead of polling, you receive a signed HTTP POST with the email data.
Setup
Create a webhook for a specific inbox:
POST /v1/webhooks
{
"url": "https://your-server.com/blip-webhook",
"inboxId": "inbox-abc"
}
Or for all inboxes in your session (omit
inboxId):{"url": "https://your-server.com/blip-webhook"}
Response:
{"webhook": {"id": "wh-123", "url": "...", "secret": "whsec_..."}}
Save the secret — you'll need it to verify signatures.
Payload
When an email arrives, Blip sends a POST to your URL:
{
"address": "swift-fox-42@bl1p.dev",
"from": "verify@example.com",
"subject": "Confirm your account",
"body_text": "Your code is 847293",
"body_html": "<p>Your code is <b>847293</b></p>",
"received_at": "2026-03-19T14:32:00Z",
"attachments": [
{"name": "file.pdf", "size": 1024, "contentType": "application/pdf"}
]
}
Signature verification
Every webhook includes an X-Blip-Signature header containing
an HMAC-SHA256 signature of the request body, signed with your webhook secret.
# Verification pseudocode
expected = HMAC-SHA256(webhook_secret, request_body)
actual = request.headers["X-Blip-Signature"]
assert timing_safe_equal(expected, actual)
Node.js example:
const crypto = require('crypto');
function verifyWebhook(body, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(body)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}
Python example:
import hmac, hashlib
def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(), body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
Retries
If your endpoint returns a non-2xx status or times out, Blip retries with exponential backoff:
| Attempt | Delay |
|---|---|
| 1st retry | ~1 minute |
| 2nd retry | ~5 minutes |
| 3rd retry (final) | ~30 minutes |
After 3 failed attempts, the delivery is marked as failed. Check delivery logs via GET /v1/webhooks/{id}/deliveries.
Management
| Action | Endpoint |
|---|---|
| List webhooks | GET /v1/webhooks |
| Toggle enabled | PATCH /v1/webhooks/{id} |
| View deliveries | GET /v1/webhooks/{id}/deliveries |
| Delete | DELETE /v1/webhooks/{id} |