Skip to main content

​
Overview

The Events API provides endpoints for creating audit trail events in the GOV.UK Notify system. Events are used for tracking system activities, user actions, and important state changes. Base URL: /events

​
Event Model

Events have the following structure:
  • id (UUID) - Unique event identifier
  • event_type (string) - Type of event being logged
  • created_at (datetime) - When the event was created
  • data (JSON) - Event-specific data payload

​
Create Event

Endpoint: POST /events Create a new event in the system.

​
Request Body

{
  "event_type": "api_key.created",
  "data": {
    "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
    "api_key_id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
    "created_by_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "key_type": "normal"
  }
}
Fields:
  • event_type (string, required) - Type of event (e.g., “api_key.created”, “service.updated”, “notification.sent”)
  • data (object, required) - JSON object containing event-specific data
  • created_at (datetime, optional) - Event creation timestamp (defaults to current time)

​
Response

Status: 201 Created 
{
  "data": {
    "id": "9876fedc-5432-10ba-9876-543210fedcba",
    "event_type": "api_key.created",
    "created_at": "2026-03-03T10:30:00.000000Z",
    "data": {
      "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
      "api_key_id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
      "created_by_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "key_type": "normal"
    }
  }
}

​
Common Event Types

While the API accepts any event type string, common patterns include:

​
Service Events

  • service.created - New service registered
  • service.updated - Service configuration changed
  • service.deleted - Service removed

​
API Key Events

  • api_key.created - New API key generated
  • api_key.revoked - API key deactivated
  • api_key.expired - API key expired

​
Template Events

  • template.created - New template created
  • template.updated - Template modified
  • template.deleted - Template archived

​
User Events

  • user.invited - User invitation sent
  • user.joined - User accepted invitation
  • user.removed - User removed from service

​
Notification Events

  • notification.sent - Notification dispatched
  • notification.delivered - Delivery confirmed
  • notification.failed - Delivery failure

​
Event Data Payload

The data field is a flexible JSON object that can contain any relevant information for the event. Common fields include: 
{
  "service_id": "UUID of the service",
  "user_id": "UUID of the user performing the action",
  "template_id": "UUID of affected template",
  "notification_id": "UUID of notification",
  "changes": {
    "field_name": {
      "old_value": "previous value",
      "new_value": "updated value"
    }
  },
  "metadata": {
    "ip_address": "User IP address",
    "user_agent": "Client user agent"
  }
}

​
Usage Examples

​
Log Service Creation

curl -X POST https://api.notifications.service.gov.uk/events \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "service.created",
    "data": {
      "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
      "service_name": "Example Service",
      "created_by_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "organisation_type": "central"
    }
  }'

​
Log Template Update

curl -X POST https://api.notifications.service.gov.uk/events \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "template.updated",
    "data": {
      "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
      "template_id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
      "updated_by_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "changes": {
        "subject": {
          "old_value": "Old Subject",
          "new_value": "New Subject"
        }
      }
    }
  }'

​
Log Failed Notification

curl -X POST https://api.notifications.service.gov.uk/events \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "notification.failed",
    "data": {
      "notification_id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
      "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
      "template_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "notification_type": "email",
      "failure_reason": "Invalid email address",
      "provider": "ses"
    }
  }'

​
Implementation Notes

​
Storage

  • Events are stored in the events table with indexed event_type for efficient querying
  • The data field uses PostgreSQL’s JSON type for flexible storage
  • Events are immutable once created (no update or delete endpoints)

​
Performance

  • Event creation is asynchronous and doesn’t block main operations
  • Consider batching events for high-volume operations
  • The created_at field is indexed for time-based queries

​
Data Retention

  • Events are retained according to the service’s data retention policy
  • Historical events provide an audit trail for compliance

​
Source Code References

  • Endpoints: /home/daytona/workspace/source/app/events/rest.py
  • Schema: /home/daytona/workspace/source/app/schemas.py:718-723
  • Model: /home/daytona/workspace/source/app/models.py:2154
  • DAO operations: /home/daytona/workspace/source/app/dao/events_dao.py

Build docs developers (and LLMs) love

Get started for freeTalk to us