Meta Events

Meta events are operational events generated by Convoy for specific activities happening within your Convoy project. This allows you to subscribe and listen for events and perform any action based on these events within your own internal systems, providing a seamless headless experience. Convoy uses webhooks to notify you of these events.

Types of event

At the moment, these are the events we currently support with plans to add some more later in the future.

Event	Description
endpoint.created	An endpoint was created
endpoint.updated	An endpoint was updated
endpoint.deleted	An endpoint was deleted
eventdelivery.success	An event delivery was successful
eventdelivery.failed	An event delivery failed

Payload Structure

Endpoints
Event Deliveries

endpoint.created

{
  event_type: "endpoint.created",
  data: {
    uid: "01H3FRSZYKNYWGPVV46RN98PM5",
    title: "testes",
    status: "active",
    secrets: [
      {
        uid: "01H3FRSZYKNYWGPVV46T42NYA8",
        value: "Vuk5LM0uujddIsqO5v_eSuz88",
        created_at: "2023-06-21T21:02:19.73106+01:00",
        deleted_at: null,
        expires_at: null,
        updated_at: "2023-06-21T21:02:19.73106+01:00"
      }
    ],
    owner_id: "582b0124-b0fe-45e0-9063-86877f797647",
    created_at: "2023-06-21T21:02:19.73104+01:00",
    deleted_at: null,
    project_id: "01H28MWP1TQV5AC5QR54BSX8HJ",
    rate_limit: 5000,
    target_url: "https://us.getconvoy.cloud/ingest/GzuS7KiIFPyyFrG5",
    updated_at: "2023-06-21T21:02:19.73104+01:00",
    description: "testing endpoint",
    http_timeout: "10s",
    authentication: null,
    advanced_signatures: false,
    rate_limit_duration: "1m0s"
  }
}

endpoint.updated

{
  event_type: "endpoint.updated",
  data: {
    uid: "01H3FRZ6SX9CDKZTEY6TMQAPWD",
    project_id: "01H28MWP1TQV5AC5QR54BSX8HJ",
    owner_id: "582b0124-b0fe-45e0-9063-86877f797647",
    target_url: "https://webhook.site/202ad8fc-653c-492a-bdaa-0ac2bd34c981",
    title: "endpoint-2",
    secrets: [
      {
        uid: "01H3FRZ6SX9CDKZTEY6V7F2Z5P",
        value: "skl2qo-2JoqAKrwD3tL3YHUt_",
        expires_at: null,
        created_at: "2023-06-21T21:05:10.589879+01:00",
        updated_at: "2023-06-21T21:05:10.589879+01:00",
        deleted_at: null
      }
    ],
    advanced_signatures: false,
    description: "",
    http_timeout: "",
    rate_limit: 5000,
    status: "active",
    rate_limit_duration: "1m0s",
    authentication: null,
    created_at: "2023-06-21T21:05:10.596435+01:00",
    updated_at: "2023-06-29T14:57:42.733584+01:00",
    deleted_at: null
  }
}

endpoint.deleted

{
	"event_type": "endpoint.deleted",
	"data": {
		"uid": "01H28MXEGATHC7TH1J3Y28WJSV",
		"project_id": "01H28MWP1TQV5AC5QR54BSX8HJ",
		"target_url": "https://us.getconvoy.cloud/ingest/GzuS7KiIFPyyFrG5",
		"title": "paystack-prod",
		"secrets": [
			{
				"uid": "01H28MXEGATHC7TH1J3YBR4G85",
				"value": "HZ00wI-b2KMmkRYDeh_9M82q2",
				"expires_at": null,
				"created_at": "2023-06-06T16:23:55.786899+01:00",
				"updated_at": "2023-06-06T16:23:55.786899+01:00",
				"deleted_at": null
			}
		],
		"advanced_signatures": false,
		"description": "",
		"http_timeout": "",
		"rate_limit": 5000,
		"status": "active",
		"rate_limit_duration": "1m0s",
		"authentication": {
			"api_key": {
				"header_value": "",
				"header_name": ""
			}
		},
		"created_at": "2023-06-06T16:23:55.792566+01:00",
		"updated_at": "2023-06-20T15:21:21.376987+01:00",
		"deleted_at": null
	}
}

eventdelivery.success

{
  event_type: "eventdelivery.success",
  data: {
    uid: "01H43Q9NS0AHAD29HTVXG997GS",
    project_id: "01H28MWP1TQV5AC5QR54BSX8HJ",
    event_id: "01H43Q9MXMX9K1XAXCCB201BTV",
    endpoint_id: "01H3FRZ6SX9CDKZTEY6TMQAPWD",
    device_id: "",
    subscription_id: "01H3FRZ6VDCJ4G8Y3979YP7TC7",
    headers: null,
    url_query_params: "",
    idempotency_key: "",
    endpoint_metadata: {
      uid: "01H3FRZ6SX9CDKZTEY6TMQAPWD",
      project_id: "01H28MWP1TQV5AC5QR54BSX8HJ",
      target_url: "https://webhook.site/202ad8fc-653c-492a-bdaa-0ac2bd34c981",
      title: "endpoint-2",
      secrets: null,
      advanced_signatures: false,
      description: "",
      http_timeout: "",
      rate_limit: 0,
      status: "",
      rate_limit_duration: "",
      authentication: null,
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    event_metadata: {
      uid: "01H43Q9MXMX9K1XAXCCB201BTV",
      event_type: "test.convoy",
      endpoints: null,
      headers: null,
      url_query_params: "",
      idempotency_key: "",
      is_duplicate_event: false,
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    source_metadata: {
      uid: "",
      project_id: "",
      mask_id: "",
      name: "",
      url: "",
      type: "",
      provider: "",
      is_disabled: false,
      verifier: null,
      custom_response: {
        body: "",
        content_type: ""
      },
      provider_config: null,
      forward_headers: null,
      pub_sub: null,
      idempotency_keys: [

      ],
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    device_metadata: {
      uid: "",
      last_seen_at: "0001-01-01T00:00:00Z",
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    attempt: {
      uid: "01H43Q9RX5T49ZCYNSGCYX0QMS",
      msg_id: "01H43Q9NS0AHAD29HTVXG997GS",
      url: "https://webhook.site/202ad8fc-653c-492a-bdaa-0ac2bd34c981",
      method: "POST",
      endpoint_id: "01H3FRZ6SX9CDKZTEY6TMQAPWD",
      api_version: "v23.06.3",
      ip_address: "[2a01:4f8:141:1d3::2]:443",
      request_http_header: {
        Content-Type: "application/json",
        User-Agent: "Convoy/v23.06.3",
        X-Convoy-Signature: "143312f3eb736911d8c17d980135414a7d37da863c8f13e7245f83131774d835"
      },
      response_http_header: {
        Cache-Control: "no-cache, private",
        Content-Type: "text/plain; charset=UTF-8",
        Date: "Thu, 29 Jun 2023 14:00:49 GMT",
        Server: "nginx",
        Vary: "Accept-Encoding",
        X-Request-Id: "77695b71-6305-43da-adec-064462422a7b",
        X-Token-Id: "202ad8fc-653c-492a-bdaa-0ac2bd34c981"
      },
      http_status: "200 OK",
      response_data: "202ad8fc-653c-492a-bdaa-0ac2bd34c981",
      status: true,
      requested_at: "2023-06-29T15:00:48.290121+01:00",
      responded_at: "2023-06-29T15:00:48.293470+01:00",
      created_at: "2023-06-29T15:00:48.29347+01:00",
      updated_at: "2023-06-29T15:00:48.29347+01:00",
      deleted_at: null
    },
    status: "Success",
    metadata: {
      data: {
        data: "test event from Convoy",
        amount: 1000,
        convoy: "https://getconvoy.io"
      },
      raw: "{\data\:\"test event from Convoy\",\convoy\:\"https://getconvoy.io\",\amount\:1000}",
      strategy: "linear",
      next_send_time: "2023-06-29T15:00:45.088735+01:00",
      num_trials: 1,
      interval_seconds: 2,
      retry_limit: 3
    },
    cli_metadata: null,
    acknowledged_at: "2023-06-29T15:00:45.090143+01:00",
    created_at: "2023-06-29T15:00:45.088743+01:00",
    updated_at: "2023-06-29T15:00:45.088743+01:00",
    deleted_at: null

}
}

eventdelivery.failed

{
  event_type: "eventdelivery.failed",
  data: {
    uid: "01H43QH6RJ6D4JV0MSAS9PHGRF",
    project_id: "01H28MWP1TQV5AC5QR54BSX8HJ",
    event_id: "01H43QH6NGWVGNZKXA31CJ6W8A",
    endpoint_id: "01H3FRZ6SX9CDKZTEY6TMQAPWD",
    device_id: "",
    subscription_id: "01H3FRZ6VDCJ4G8Y3979YP7TC7",
    headers: null,
    url_query_params: "",
    idempotency_key: "",
    endpoint_metadata: {
      uid: "01H3FRZ6SX9CDKZTEY6TMQAPWD",
      project_id: "01H28MWP1TQV5AC5QR54BSX8HJ",
      target_url: "https://webhook.site/202ad8fc-653c-492a-bdaa-0ac2bd34c981",
      title: "endpoint-2",
      secrets: null,
      advanced_signatures: false,
      description: "",
      http_timeout: "",
      rate_limit: 0,
      status: "",
      rate_limit_duration: "",
      authentication: null,
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    event_metadata: {
      uid: "01H43QH6NGWVGNZKXA31CJ6W8A",
      event_type: "test.convoy",
      endpoints: null,
      headers: null,
      url_query_params: "",
      idempotency_key: "",
      is_duplicate_event: false,
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    source_metadata: {
      uid: "",
      project_id: "",
      mask_id: "",
      name: "",
      url: "",
      type: "",
      provider: "",
      is_disabled: false,
      verifier: null,
      custom_response: {
        body: "",
        content_type: ""
      },
      provider_config: null,
      forward_headers: null,
      pub_sub: null,
      idempotency_keys: [

      ],
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    device_metadata: {
      uid: "",
      last_seen_at: "0001-01-01T00:00:00Z",
      created_at: "0001-01-01T00:00:00Z",
      updated_at: "0001-01-01T00:00:00Z",
      deleted_at: null
    },
    attempt: {
      uid: "01H43QHJQV5BE376GTNPY196GZ",
      msg_id: "01H43QH6RJ6D4JV0MSAS9PHGRF",
      url: "https://webhook.site/202ad8fc-653c-492a-bdaa-0ac2bd34c981",
      method: "POST",
      endpoint_id: "01H3FRZ6SX9CDKZTEY6TMQAPWD",
      api_version: "v23.06.3",
      ip_address: "46.4.105.116",
      request_http_header: {
        Content-Type: "application/json",
        User-Agent: "Convoy/v23.06.3",
        X-Convoy-Signature: "143312f3eb736911d8c17d980135414a7d37da863c8f13e7245f83131774d835"
      },
      http_status: "",
      status: false,
      error: "Post \"https://webhook.site/202ad8fc-653c-492a-bdaa-0ac2bd34c981\": context deadline exceeded (Client.Timeout exceeded while awaiting headers)",
      requested_at: "2023-06-29T15:05:04.123567+01:00",
      created_at: "2023-06-29T15:05:04.123567+01:00",
      updated_at: "2023-06-29T15:05:04.123567+01:00",
      deleted_at: null
    },
    status: "Failure",
    metadata: {
      data: {
        data: "test event from Convoy",
        amount: 1000,
        convoy: "https://getconvoy.io"
      },
      raw: "{\data\:\"test event from Convoy\",\convoy\:\"https://getconvoy.io\",\amount\:1000}",
      strategy: "linear",
      next_send_time: "2023-06-29T15:05:06.123529+01:00",
      num_trials: 3,
      interval_seconds: 2,
      retry_limit: 3
    },
    cli_metadata: null,
    description: "Retry limit exceeded",
    acknowledged_at: "2023-06-29T15:04:51.860041+01:00",
    created_at: "2023-06-29T15:04:51.858865+01:00",
    updated_at: "2023-06-29T15:04:59.138633+01:00",
    deleted_at: null
  }
}

For eventdelivery.failed, the failure reason is available as data.description (for example Retry limit exceeded). For lower-level network/request errors, data.attempt.error carries the underlying error (for example a timeout, connection refused, DNS, or TLS error), as shown above. data.attempt.error is only present when the request failed before a response was received; when the endpoint returns an HTTP response (for example 400 or 500), data.attempt.http_status is set instead and data.attempt.error is omitted. data.attempt.ip_address is the resolved endpoint address; it is populated once a connection is established (so it is empty on DNS or connection-refused failures, but present on a response timeout like the one above). Both eventdelivery.success and eventdelivery.failed also include delivery timestamps: data.acknowledged_at is when Convoy accepted and queued the delivery (the start of the latency clock), data.attempt.requested_at is when Convoy sent the HTTP request, and data.attempt.responded_at is when the response came back. responded_at is omitted when no response was received (for example a timeout or connection failure), as in the failed example above. Meta events are completely optional and can be turned on under the Project settings page. All you need to do is provide a webhook URL to receive these events, a secret for signing the payload (optional) and the events you would like to subscribe to.

Viewing Meta Events

You can also view a list of all your Meta events.

Meta Event Signature

We use the secret either provided by you or generated by us to sign the payload using SHA256 hashing algorithm and hex encoding. The value is contained in the X-Convoy-Signature header, and you can use that to validate that the event was sent by Convoy.

​Types of event

​Payload Structure

​Viewing Meta Events

​Meta Event Signature

Types of event

Payload Structure

Viewing Meta Events

Meta Event Signature