API Reference

Webhooks

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Webhook Events

Webhooks are HTTP requests sent by OpenAI to a URL you specify when certain events happen during the course of API usage.

Learn more about webhooks.

response.completed

Sent when a background response has been completed.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the model response was completed.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the model response.

type: "response.completed"

The type of the event. Always response.completed.

object: optional "event"

The object of the event. Always event.

OBJECT

response.completed

{
  "id": "evt_abc123",
  "type": "response.completed",
  "created_at": 1719168000,
  "data": {
    "id": "resp_abc123"
  }
}

response.cancelled

Sent when a background response has been cancelled.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the model response was cancelled.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the model response.

type: "response.cancelled"

The type of the event. Always response.cancelled.

object: optional "event"

The object of the event. Always event.

OBJECT

response.cancelled

{
  "id": "evt_abc123",
  "type": "response.cancelled",
  "created_at": 1719168000,
  "data": {
    "id": "resp_abc123"
  }
}

response.failed

Sent when a background response has failed.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the model response failed.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the model response.

type: "response.failed"

The type of the event. Always response.failed.

object: optional "event"

The object of the event. Always event.

OBJECT

response.failed

{
  "id": "evt_abc123",
  "type": "response.failed",
  "created_at": 1719168000,
  "data": {
    "id": "resp_abc123"
  }
}

response.incomplete

Sent when a background response has been interrupted.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the model response was interrupted.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the model response.

type: "response.incomplete"

The type of the event. Always response.incomplete.

object: optional "event"

The object of the event. Always event.

OBJECT

response.incomplete

{
  "id": "evt_abc123",
  "type": "response.incomplete",
  "created_at": 1719168000,
  "data": {
    "id": "resp_abc123"
  }
}

batch.completed

Sent when a batch API request has been completed.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the batch API request was completed.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the batch API request.

type: "batch.completed"

The type of the event. Always batch.completed.

object: optional "event"

The object of the event. Always event.

OBJECT

batch.completed

{
  "id": "evt_abc123",
  "type": "batch.completed",
  "created_at": 1719168000,
  "data": {
    "id": "batch_abc123"
  }
}

batch.cancelled

Sent when a batch API request has been cancelled.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the batch API request was cancelled.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the batch API request.

type: "batch.cancelled"

The type of the event. Always batch.cancelled.

object: optional "event"

The object of the event. Always event.

OBJECT

batch.cancelled

{
  "id": "evt_abc123",
  "type": "batch.cancelled",
  "created_at": 1719168000,
  "data": {
    "id": "batch_abc123"
  }
}

batch.expired

Sent when a batch API request has expired.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the batch API request expired.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the batch API request.

type: "batch.expired"

The type of the event. Always batch.expired.

object: optional "event"

The object of the event. Always event.

OBJECT

batch.expired

{
  "id": "evt_abc123",
  "type": "batch.expired",
  "created_at": 1719168000,
  "data": {
    "id": "batch_abc123"
  }
}

batch.failed

Sent when a batch API request has failed.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the batch API request failed.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the batch API request.

type: "batch.failed"

The type of the event. Always batch.failed.

object: optional "event"

The object of the event. Always event.

OBJECT

batch.failed

{
  "id": "evt_abc123",
  "type": "batch.failed",
  "created_at": 1719168000,
  "data": {
    "id": "batch_abc123"
  }
}

fine_tuning.job.succeeded

Sent when a fine-tuning job has succeeded.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the fine-tuning job succeeded.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the fine-tuning job.

type: "fine_tuning.job.succeeded"

The type of the event. Always fine_tuning.job.succeeded.

object: optional "event"

The object of the event. Always event.

OBJECT

fine_tuning.job.succeeded

{
  "id": "evt_abc123",
  "type": "fine_tuning.job.succeeded",
  "created_at": 1719168000,
  "data": {
    "id": "ftjob_abc123"
  }
}

fine_tuning.job.failed

Sent when a fine-tuning job has failed.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the fine-tuning job failed.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the fine-tuning job.

type: "fine_tuning.job.failed"

The type of the event. Always fine_tuning.job.failed.

object: optional "event"

The object of the event. Always event.

OBJECT

fine_tuning.job.failed

{
  "id": "evt_abc123",
  "type": "fine_tuning.job.failed",
  "created_at": 1719168000,
  "data": {
    "id": "ftjob_abc123"
  }
}

fine_tuning.job.cancelled

Sent when a fine-tuning job has been cancelled.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the fine-tuning job was cancelled.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the fine-tuning job.

type: "fine_tuning.job.cancelled"

The type of the event. Always fine_tuning.job.cancelled.

object: optional "event"

The object of the event. Always event.

OBJECT

fine_tuning.job.cancelled

{
  "id": "evt_abc123",
  "type": "fine_tuning.job.cancelled",
  "created_at": 1719168000,
  "data": {
    "id": "ftjob_abc123"
  }
}

eval.run.succeeded

Sent when an eval run has succeeded.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the eval run succeeded.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the eval run.

type: "eval.run.succeeded"

The type of the event. Always eval.run.succeeded.

object: optional "event"

The object of the event. Always event.

OBJECT

eval.run.succeeded

{
  "id": "evt_abc123",
  "type": "eval.run.succeeded",
  "created_at": 1719168000,
  "data": {
    "id": "evalrun_abc123"
  }
}

eval.run.failed

Sent when an eval run has failed.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the eval run failed.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the eval run.

type: "eval.run.failed"

The type of the event. Always eval.run.failed.

object: optional "event"

The object of the event. Always event.

OBJECT

eval.run.failed

{
  "id": "evt_abc123",
  "type": "eval.run.failed",
  "created_at": 1719168000,
  "data": {
    "id": "evalrun_abc123"
  }
}

eval.run.canceled

Sent when an eval run has been canceled.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the eval run was canceled.

formatunixtime

data: object { id }

Event data payload.

id: string

The unique ID of the eval run.

type: "eval.run.canceled"

The type of the event. Always eval.run.canceled.

object: optional "event"

The object of the event. Always event.

OBJECT

eval.run.canceled

{
  "id": "evt_abc123",
  "type": "eval.run.canceled",
  "created_at": 1719168000,
  "data": {
    "id": "evalrun_abc123"
  }
}

realtime.call.incoming

Sent when an incoming API SIP session is available for Realtime acceptance. The same pending session can also emit live.transport.incoming; the first successful Realtime or Live accept endpoint selects the runtime surface.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the model response was completed.

formatunixtime

data: object { call_id, sip_headers, sip_media_security }

Event data payload.

call_id: string

The ID of the pending SIP call. Pass this value unchanged when accepting or rejecting the call through the Realtime API. For the Live API, use the session_id from live.transport.incoming instead.

sip_headers: array of object { name, value }

Headers from the SIP INVITE, excluding SIP authorization headers. Retained names, values, repeated entries, and order are preserved. Treat these values as untrusted call metadata.

name: string

Name of the SIP Header.

value: string

Value of the SIP Header.

sip_media_security: optional "rtp" or "srtp" or string

Media protection selected on the SIP leg during SDP negotiation. srtp indicates SRTP; rtp indicates unencrypted RTP. Omitted when unknown. This does not describe SIP signaling security or confirm that media has flowed. Clients should handle unrecognized values as unknown.

One of the following:

"rtp" or "srtp"

Media protection selected on the SIP leg during SDP negotiation. srtp indicates SRTP; rtp indicates unencrypted RTP. Omitted when unknown. This does not describe SIP signaling security or confirm that media has flowed. Clients should handle unrecognized values as unknown.

One of the following:

"rtp"

"srtp"

string

type: "realtime.call.incoming"

The type of the event. Always realtime.call.incoming.

object: optional "event"

The object of the event. Always event.

OBJECT

realtime.call.incoming

{
  "id": "evt_abc123",
  "type": "realtime.call.incoming",
  "created_at": 1719168000,
  "data": {
    "call_id": "rtc_u0_479a275623b54bdb9b6fbae2f7cbd408",
    "sip_media_security": "srtp",
    "sip_headers": [
      {"name": "Max-Forwards", "value": "63"},
      {"name": "CSeq", "value": "851287 INVITE"},
      {"name": "Content-Type", "value": "application/sdp"}
    ]
  }
}

live.call.incoming

Deprecated: use live.transport.incoming. Retained for existing subscriptions during migration; new subscriptions to this event are not allowed. Sent when an incoming API SIP session is available for Live acceptance. The same pending session can also emit realtime.call.incoming; the first successful Realtime or Live accept endpoint selects the runtime surface.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the event was created.

formatunixtime

data: object { session_id, sip_headers, sip_media_security }

Event data payload.

session_id: string

The live_... ID of the pending SIP session. Pass this value unchanged to Live call controls and sideband connections. The corresponding realtime.call.incoming event uses a separate rtc_... call ID.

sip_headers: array of object { name, value }

Headers from the SIP INVITE, excluding SIP authorization headers. Retained names, values, repeated entries, and order are preserved. Treat these values as untrusted call metadata.

name: string

Name of the SIP Header.

value: string

Value of the SIP Header.

sip_media_security: optional "rtp" or "srtp" or string

Media protection selected on the SIP leg during SDP negotiation. srtp indicates SRTP; rtp indicates unencrypted RTP. Omitted when unknown. This does not describe SIP signaling security or confirm that media has flowed. Clients should handle unrecognized values as unknown.

One of the following:

"rtp" or "srtp"

Media protection selected on the SIP leg during SDP negotiation. srtp indicates SRTP; rtp indicates unencrypted RTP. Omitted when unknown. This does not describe SIP signaling security or confirm that media has flowed. Clients should handle unrecognized values as unknown.

One of the following:

"rtp"

"srtp"

string

type: "live.call.incoming"

The type of the event. Always live.call.incoming.

object: optional "event"

The object of the event. Always event.

OBJECT

live.call.incoming

{
  "id": "evt_abc123",
  "type": "live.call.incoming",
  "created_at": 1719168000,
  "data": {
    "session_id": "live_u0_479a275623b54bdb9b6fbae2f7cbd408",
    "sip_media_security": "srtp",
    "sip_headers": [
      {"name": "From", "value": "<sip:alice@example.com>;tag=abc123"},
      {"name": "To", "value": "<sip:recipient@example.com>"},
      {"name": "Call-ID", "value": "call-123@example.com"}
    ]
  }
}

live.transport.incoming

Sent when an incoming API SIP session is available for Live acceptance. The same pending session can also emit realtime.call.incoming; the first successful Realtime or Live accept endpoint selects the runtime surface.

id: string

The unique ID of the event.

created_at: number

The Unix timestamp (in seconds) of when the event was created.

formatunixtime

data: object { session_id, sip_headers, type, sip_media_security }

Event data payload.

session_id: string

The live_... ID of the pending SIP session. Forward this value unchanged when accepting or rejecting the call through the Live API.

sip_headers: array of object { name, value }

Headers from the SIP INVITE, excluding SIP authorization headers. Retained names, values, repeated entries, and order are preserved. Treat these values as untrusted call metadata.

name: string

Name of the SIP Header.

value: string

Value of the SIP Header.

type: "sip"

The incoming transport type. Always sip.

sip_media_security: optional "rtp" or "srtp" or string

Media protection selected on the SIP leg during SDP negotiation. srtp indicates SRTP; rtp indicates unencrypted RTP. Omitted when unknown. This does not describe SIP signaling security or confirm that media has flowed. Clients should handle unrecognized values as unknown.

One of the following:

"rtp" or "srtp"

Media protection selected on the SIP leg during SDP negotiation. srtp indicates SRTP; rtp indicates unencrypted RTP. Omitted when unknown. This does not describe SIP signaling security or confirm that media has flowed. Clients should handle unrecognized values as unknown.

One of the following:

"rtp"

"srtp"

string

type: "live.transport.incoming"

The type of the event. Always live.transport.incoming.

object: optional "event"

The object of the event. Always event.

OBJECT

live.transport.incoming

{
  "id": "evt_abc123",
  "type": "live.transport.incoming",
  "created_at": 1719168000,
  "data": {
    "type": "sip",
    "session_id": "live_u0_479a275623b54bdb9b6fbae2f7cbd408",
    "sip_media_security": "srtp",
    "sip_headers": [
      {"name": "From", "value": "<sip:alice@example.com>;tag=abc123"},
      {"name": "To", "value": "<sip:recipient@example.com>"},
      {"name": "Call-ID", "value": "call-123@example.com"}
    ]
  }
}

safety.warning_issued

Sent when a warning is issued for a safety identifier in your organization.

id: string

The unique ID of the webhook event.

created_at: number

The Unix timestamp in seconds when the event was created.

formatunixtime

data: object { id }

id: string

The safety case ID to pass to GET /v1/safety/cases/{id}.

object: "event"

Always event.

type: "safety.warning_issued"

Always safety.warning_issued.

OBJECT

safety.warning_issued

{
  "id": "evt_123",
  "object": "event",
  "created_at": 1787659200,
  "type": "safety.warning_issued",
  "data": {"id": "C-abc123"}
}

safety.deactivation_issued

Sent when a deactivation is issued for a safety identifier in your organization.

id: string

The unique ID of the webhook event.

created_at: number

The Unix timestamp in seconds when the event was created.

formatunixtime

data: object { id }

id: string

The safety case ID to pass to GET /v1/safety/cases/{id}.

object: "event"

Always event.

type: "safety.deactivation_issued"

Always safety.deactivation_issued.

OBJECT

safety.deactivation_issued

{
  "id": "evt_123",
  "object": "event",
  "created_at": 1787659200,
  "type": "safety.deactivation_issued",
  "data": {"id": "C-abc123"}
}

safety.alert.created

Sent when an approved safety alert is available for an API project.

id: string

The unique ID of the webhook event.

created_at: number

The Unix timestamp in seconds when the event was created.

formatunixtime

data: object { id }

id: string

The safety alert ID to pass to GET /v1/safety/alerts/{id}.

object: "event"

Always event.

type: "safety.alert.created"

Always safety.alert.created.

OBJECT

safety.alert.created

{
  "id": "evt_123",
  "object": "event",
  "created_at": 1787659200,
  "type": "safety.alert.created",
  "data": {"id": "alert_0123456789abcdef0123456789abcdef"}
}

safety.org_alert.created

Sent when an approved safety alert is available for an enterprise workspace.

id: string

The unique ID of the webhook event.

created_at: number

The Unix timestamp in seconds when the event was created.

formatunixtime

data: object { id }

id: string

The safety alert ID to pass to GET /v1/safety/alerts/{id}.

object: "event"

Always event.

type: "safety.org_alert.created"

Always safety.org_alert.created.

OBJECT

safety.org_alert.created

{
  "id": "evt_123",
  "object": "event",
  "created_at": 1787659200,
  "type": "safety.org_alert.created",
  "data": {"id": "alert_0123456789abcdef0123456789abcdef"}
}