Skip to main content
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
  }
}

​
Payload format

{
  "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

EventDescription
product.createdA new product was added
product.updatedProduct data was modified
product.impact_updatedImpact score was recalculated
product.deletedA product was removed

​
Order events

EventDescription
order.createdA new order was recorded
order.carbon_calculatedOrder carbon footprint was computed

​
Compliance events

EventDescription
dpp.generatedDigital Product Passport was created
dpp.updatedDPP was updated
epd.ingestedEPD document was parsed
epd.validation_failedEPD parsing failed
mki.calculatedMKI score was computed

​
Report events

EventDescription
report.generatedCSRD/ESG report was generated

​
Visualisation events

EventDescription
render.completedAsset rendering finished
render.failedAsset rendering failed

​
Retry policy

AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours
612 hours
After 6 failed attempts, the webhook is marked as 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 }
}