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://dashboard.getconvoy.io/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://dashboard.getconvoy.io/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",
      status: true,
      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,
    created_at: "2023-06-29T15:00:45.088743+01:00",
    updated_at: "2023-06-29T15:00:45.088743+01:00",
    deleted_at: null

}
}

eventdelivery.failure

{
  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: "[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:05:05 GMT",
        Server: "nginx",
        X-Request-Id: "c1a3908f-92f7-4920-9ecd-e269eca15c6a",
        X-Token-Id: "202ad8fc-653c-492a-bdaa-0ac2bd34c981"
      },
      http_status: "400 Bad Request",
      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",
    created_at: "2023-06-29T15:04:51.858865+01:00",
    updated_at: "2023-06-29T15:04:59.138633+01:00",
    deleted_at: null
  }
}

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.

Home

Guides

Deployment

Product Manual

Command Line

SDK

Cloud

Legal

Business & Enterprise

Resources

FAQ

Meta Events

Types of event

Payload Structure

Viewing Meta Events

Meta Event Signature

Home

Guides

Deployment

Product Manual

Command Line

SDK

Cloud

Legal

Business & Enterprise

Resources

FAQ

​Types of event

​Payload Structure

​Viewing Meta Events

​Meta Event Signature

Types of event

Payload Structure

Viewing Meta Events

Meta Event Signature