--- updatedAt: 2026-07-01T18:06:48.000Z --- # Partner-Fault Refund Webhook Callback **Beta** Sent by Deliveroo to your configured webhook endpoint when a partner-fault refund has been applied to an order. The request is signed with the `x-deliveroo-sequence-guid` and `x-deliveroo-hmac-sha256` headers, which you should use to verify authenticity before processing. Acknowledge the callback with any `2xx` status code. If we receive a non-2xx response we treat it as a failure and retry the delivery. See the [Partner-Fault Refund Webhook guide](https://api-docs.deliveroo.com/docs/refund-webhook) for signature verification, idempotency, responses, and retry behaviour. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Partner-Fault Refund Webhook (Beta)", "version": "1.0", "description": "**Beta**\n\nDeliveroo POSTs this webhook to your configured endpoint whenever a partner-fault\nrefund has been applied to an order — for example when items were missing or\nunavailable and the shortfall has been refunded to the customer at the partner's\ncost. The payload tells you which refund was applied, against which order and\nlocation, the total refunded amount, and the per-item breakdown so you can\nreconcile it against your own systems.\n\nEach request is signed. Verify the `x-deliveroo-hmac-sha256` header using your\nwebhook secret and the `x-deliveroo-sequence-guid` before trusting the payload.\n\nRespond with any `2xx` status code to acknowledge receipt. Non-2xx responses are\ntreated as a delivery failure and the callback will be retried.\n\nSee the [Partner-Fault Refund Webhook guide](https://api-docs.deliveroo.com/docs/refund-webhook)\nfor signature verification, idempotency, responses, and retry behaviour.", "contact": { "name": "Partner-Fault Refunds" } }, "x-readme": { "explorer-enabled": false }, "paths": { "/partner-fault-refund": { "post": { "summary": "Partner-Fault Refund Webhook Callback", "description": "**Beta**\n\nSent by Deliveroo to your configured webhook endpoint when a partner-fault\nrefund has been applied to an order. The request is signed with the\n`x-deliveroo-sequence-guid` and `x-deliveroo-hmac-sha256` headers, which you\nshould use to verify authenticity before processing.\n\nAcknowledge the callback with any `2xx` status code. If we receive a non-2xx\nresponse we treat it as a failure and retry the delivery.\n\nSee the [Partner-Fault Refund Webhook guide](https://api-docs.deliveroo.com/docs/refund-webhook)\nfor signature verification, idempotency, responses, and retry behaviour.", "operationId": "partner-fault-refund-webhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/SequenceGuid" }, { "$ref": "#/components/parameters/Hmac" } ], "requestBody": { "$ref": "#/components/requestBodies/PartnerFaultRefundCallback" }, "responses": { "2XX": { "description": "Your server returns any 2xx status code to acknowledge the callback." }, "4XX": { "description": "Your server can return 4XX codes to signal its issues with the request." }, "5XX": { "description": "Your server can return 5XX codes to signal its internal issues." } } } } }, "components": { "parameters": { "SequenceGuid": { "in": "header", "name": "x-deliveroo-sequence-guid", "description": "Deliveroo sequential globally unique identifier (GUID) for the delivery attempt. Please implement it as case-insensitive.", "schema": { "type": "string" }, "required": true, "example": "1499765769" }, "Hmac": { "in": "header", "name": "x-deliveroo-hmac-sha256", "description": "On registration, we'll provide you with a webhook secret. We'll use the webhook secret and the sequential globally unique identifier (GUID) to generate a hash of the payload. When you receive a POST request, you will be able to compute a hash and verify that it's a genuine, authorized request sent from Deliveroo. Please implement it as case-insensitive.", "schema": { "type": "string" }, "required": true, "example": "cc28251639033853f1cd1f8bde5a75cefba53c7c991d2b0db848b6747e258678" } }, "schemas": { "RefundItem": { "title": "Refund Item", "type": "object", "description": "A single refunded line in the refund.", "properties": { "id": { "title": "Item ID", "description": "Deliveroo's unique identifier for the refunded order item.", "type": "string" }, "pos_item_id": { "title": "In-Store System Item ID", "description": "The PLU of the item.", "type": "string" }, "name": { "title": "Name", "description": "The item's name.", "type": "string" }, "quantity": { "title": "Quantity", "description": "The refunded quantity for this item.", "type": "integer", "format": "int32" }, "refund_amount": { "title": "Item Refund Amount", "description": "The exact per-item consumer charge that was refunded, in the minor unit of the currency (e.g. pence, cents).", "type": "integer", "format": "int64" } } }, "RefundPayload": { "title": "Partner-Fault Refund", "type": "object", "properties": { "refund_id": { "title": "Refund ID", "description": "Deliveroo's unique identifier for this refund. Use this as your idempotency key — deduplicate on this field (see [Responding, failures & retries](https://api-docs.deliveroo.com/docs/refund-webhook#responding-failures--retries)).", "type": "string" }, "order_id": { "title": "Order ID", "description": "The order the refund relates to, as the market segment followed by the order DRN id (e.g. `gb:ec42e5fc-5587-46df-b79a-99b007c5c71f`).", "type": "string" }, "order_number": { "title": "Order Numeric ID", "description": "Deliveroo's numeric order id (e.g. `50024576064`).", "type": "string", "example": "50024576064" }, "location_id": { "title": "Location ID", "description": "The partner's location ID for the site the order belongs to.", "type": "string" }, "brand_id": { "title": "Brand ID", "description": "The partner's brand identifier.", "type": "string" }, "reason_code": { "title": "Reason Code", "description": "The refund-level reason code. Always present; may be an empty string.", "type": "string" }, "applied_at": { "title": "Applied At", "description": "Date and time in the RFC3339 (ISO-8601) format, in UTC, when the refund was applied.", "type": "string", "format": "date-time" }, "currency": { "title": "Currency", "description": "The order-level currency as the international 3-letter code defined by the ISO 4217 standard.", "type": "string" }, "refund_amount": { "title": "Refund Amount", "description": "Total refund amount for the claim, in the minor unit of the currency (e.g. pence, cents). This should equal the sum of the item-level refund amounts.", "type": "integer", "format": "int64" }, "items": { "title": "Items", "description": "The per-line breakdown of what was refunded.", "type": "array", "items": { "$ref": "#/components/schemas/RefundItem" } } } } }, "requestBodies": { "PartnerFaultRefundCallback": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundPayload" }, "examples": { "PartnerFaultRefund": { "summary": "Partner-Fault Refund", "value": { "refund_id": "crq-abc", "order_id": "gb:ec42e5fc-5587-46df-b79a-99b007c5c71f", "order_number": "50024576064", "location_id": "loc-001", "brand_id": "brand-drn-001", "reason_code": "items_unavailable", "applied_at": "2024-03-15T10:30:00Z", "currency": "GBP", "refund_amount": 500, "items": [ { "id": "item-1", "pos_item_id": "PLU-001", "name": "Organic Milk", "quantity": 2, "refund_amount": 350 }, { "id": "item-2", "pos_item_id": "PLU-002", "name": "Bread", "quantity": 1, "refund_amount": 100 } ] } } } } } } } }, "tags": [ { "name": "Webhooks" } ] } ```