Callback Configuration

Internal API endpoints for managing service callback configurations

Overview

Callback endpoints allow services to register webhooks that GOV.UK Notify will call when specific events occur (delivery receipts, inbound SMS, returned letters).

Base URL: /service/{service_id}/callback-api

Callback Types

• delivery_status - Delivery receipt callbacks
• inbound_sms - Inbound SMS callbacks
• returned_letter - Returned letter callbacks
• complaint - Email complaint callbacks

Create Callback

Endpoint: POST /service/{service_id}/callback-api

Register a new callback URL for a service.

Path Parameters

• service_id (UUID, required) - Service identifier

Request Body

{
  "url": "https://example.com/callbacks/notify",
  "bearer_token": "your-bearer-token-min-10-chars",
  "updated_by_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
  "callback_type": "delivery_status"
}

Fields:

• url (string, required) - HTTPS callback URL
• bearer_token (string, required) - Bearer token (minimum 10 characters)
• updated_by_id (UUID, required) - User who created the callback
• callback_type (string, optional) - Type of callback

Response

Status: 201 Created

{
  "data": {
    "id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
    "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
    "url": "https://example.com/callbacks/notify",
    "bearer_token": "your-bearer-token-min-10-chars",
    "callback_type": "delivery_status",
    "created_at": "2026-03-03T10:30:00.000000Z",
    "updated_at": null,
    "updated_by_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6"
  }
}

Error Responses

Status: 400 Bad Request

{
  "result": "error",
  "message": {
    "name": ["You can only have one URL and bearer token for your service."]
  }
}

Returned when a callback of the same type already exists for this service.

Status: 404 Not Found

{
  "result": "error",
  "message": "No result found"
}

Returned when the service_id doesn’t exist.

Update Callback

Endpoint: POST /service/{service_id}/callback-api/{callback_api_id}

Update an existing callback configuration.

Path Parameters

• service_id (UUID, required) - Service identifier
• callback_api_id (UUID, required) - Callback API identifier

Request Body

{
  "url": "https://example.com/callbacks/notify-v2",
  "bearer_token": "new-bearer-token-value",
  "updated_by_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
  "callback_type": "delivery_status"
}

Fields:

• updated_by_id (UUID, required) - User making the update
• callback_type (string, required) - Type of callback
• url (string, optional) - New callback URL
• bearer_token (string, optional) - New bearer token

Response

Status: 200 OK

{
  "data": {
    "id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
    "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
    "url": "https://example.com/callbacks/notify-v2",
    "bearer_token": "new-bearer-token-value",
    "callback_type": "delivery_status",
    "created_at": "2026-03-03T10:30:00.000000Z",
    "updated_at": "2026-03-03T14:15:00.000000Z",
    "updated_by_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6"
  }
}

Get Callback

Endpoint: GET /service/{service_id}/callback-api/{callback_api_id}

Retrieve a callback configuration.

Path Parameters

• service_id (UUID, required) - Service identifier
• callback_api_id (UUID, required) - Callback API identifier

Query Parameters

• callback_type (string, optional) - Type of callback to retrieve

Response

Status: 200 OK

{
  "data": {
    "id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
    "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
    "url": "https://example.com/callbacks/notify",
    "bearer_token": "your-bearer-token-min-10-chars",
    "callback_type": "delivery_status",
    "created_at": "2026-03-03T10:30:00.000000Z",
    "updated_at": null,
    "updated_by_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6"
  }
}

Delete Callback

Endpoint: DELETE /service/{service_id}/callback-api/{callback_api_id}

Delete a callback configuration.

Path Parameters

• service_id (UUID, required) - Service identifier
• callback_api_id (UUID, required) - Callback API identifier

Query Parameters

• callback_type (string, optional) - Type of callback to delete

Response

Status: 204 No Content

No response body on successful deletion.

Error Responses

Status: 404 Not Found

{
  "errors": [
    {
      "error": "InvalidRequest",
      "message": "Service delivery receipt API not found"
    }
  ]
}

Error messages vary by callback type:

• delivery_status: “Service delivery receipt API not found”
• inbound_sms: “Service inbound API not found”
• returned_letter: “Service returned letter API not found”

Implementation Notes

Security

• Bearer tokens are encrypted before storage (see /home/daytona/workspace/source/app/models.py:886)
• All callback URLs must use HTTPS
• Bearer token minimum length is 10 characters

Constraints

• Each service can only have one callback URL per callback type
• The service_id and callback_type combination must be unique
• Database constraint: uix_service_callback_type

Source Code References

• Endpoints: /home/daytona/workspace/source/app/service/callback_rest.py
• Schema validation: /home/daytona/workspace/source/app/service/service_callback_api_schema.py
• Model: /home/daytona/workspace/source/app/models.py:886
• DAO operations: /home/daytona/workspace/source/app/dao/service_callback_api_dao.py