Documentation Index
Fetch the complete documentation index at: https://docs.heychocolate.com/llms.txt
Use this file to discover all available pages before exploring further.
Webhooks deliver real-time HTTP callbacks when events occur in Hey Chocolate.
Setup
Configure endpoints in the Dashboard or via the API:
mutation {
createWebhook(input: {
url: "https://your-app.com/webhooks/heychocolate"
events: [PRODUCT_IMPACT_UPDATED, ORDER_CARBON_CALCULATED, DPP_GENERATED]
secret: "whsec_your_signing_secret"
}) {
id
url
events
status
}
}
{
"id": "evt_abc123",
"type": "product.impact_updated",
"createdAt": "2025-09-01T12:00:00Z",
"data": {
"productId": "prod_abc123",
"previousScore": { "co2Equivalent": 14.2 },
"newScore": { "co2Equivalent": 12.4 },
"reason": "EPD data updated"
}
}
Signature verification
Verify the X-HC-Signature header to ensure requests are from Hey Chocolate:
import crypto from 'crypto';
function verifyWebhookSignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(`sha256=${expected}`)
);
}
Event types
Product events
| Event | Description |
|---|
product.created | A new product was added |
product.updated | Product data was modified |
product.impact_updated | Impact score was recalculated |
product.deleted | A product was removed |
Order events
| Event | Description |
|---|
order.created | A new order was recorded |
order.carbon_calculated | Order carbon footprint was computed |
Compliance events
| Event | Description |
|---|
dpp.generated | Digital Product Passport was created |
dpp.updated | DPP was updated |
epd.ingested | EPD document was parsed |
epd.validation_failed | EPD parsing failed |
mki.calculated | MKI score was computed |
Report events
| Event | Description |
|---|
report.generated | CSRD/ESG report was generated |
Visualisation events
| Event | Description |
|---|
render.completed | Asset rendering finished |
render.failed | Asset rendering failed |
Retry policy
| Attempt | Delay |
|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 12 hours |
FAILED and can be re-enabled from the Dashboard.
Managing webhooks
query {
webhooks {
id
url
events
status
lastDelivery { status responseCode deliveredAt }
}
}
mutation {
deleteWebhook(id: "wh_abc123") { success }
}
