Configuration

{
  // [optional] 
  // Convoy uses a backwards-compatible api verisioning strategy 
  // for the REST API. This config specifies which version your 
  // instance should use. The environment variable equivalent is 
  // CONVOY_API_VERSION. The default value is the latest at the time of release.
  "api_version": "2024-01-01",

  // [optional] 
  // This is used to specify the host the server is running on. 
  // It is used in emails with links to access the instance. 
  // E.g. user invitation. The environment variable equivalent is 
  // CONVOY_HOST. The default value is localhost. 
  "host": "hooks.domain.com",

  // [required]
  // Database configuration for your instance. As of this writing, 
  // Convoy only supports PostgreSQL.
  "database": {
    // Database host URL. The environment variable equivalent is 
    // CONVOY_DB_HOST. The default value is localhost.
    "host": "localhost",

    // Database scheme. The environment variable equivalent is 
    // CONVOY_DB_SCHEME. The default value is postgres.
    "scheme": "postgres",

    // Database username. The environment equivalent is 
    // CONVOY_DB_USERNAME. The default is postgres.
    "username": "postgres",

    // Database password. The environment equivalent is 
    // CONVOY_DB_PASSWORD. The default is postgres.
    "password": "postgres",

    // Database name. The environment equivalent is 
    // CONVOY_DB_DATABASE. The default is convoy.
    "database": "convoy",

    // Database options. The environment equivalent is 
    // CONVOY_DB_OPTIONS. 
    "options": "sslmode=disable&connect_timeout=30",
    
    // Database port. The environment equivalent is 
    // CONVOY_DB_PORT. The default value is 5432.
    "port": 5432

    // This is used to tune the connection to the database 
    // for maximum performance. It specifies the maximum 
    // amount of open connections allowed in the connection pool.
    // The environment variable equivalent is CONVOY_DB_MAX_OPEN_CONN
    "max_open_conn": 10,

    // This is used to tune the connection to the database 
    // for maximum performance. It specifies how many idle 
    // connections are allowed in the connection pool.
    // The environment variable equivalent is CONVOY_DB_MAX_IDLE_CONN
    "max_idle_conn": 10,

    // This is used to tune the connection to the database
    // for maximum performance. It specifies how long any 
    // connection is kept in the pool before being killed.
    // The environment variable equivalent is CONVOY_DB_CONN_MAX_LIFETIME
    "conn_max_lifetime": 10
  },

  [required]
  // Each Convoy component, includes a server component. This is used to 
  // configure the server on each component.
  "server": {

      "http": {

          // This is a boolean flag used to determine if ssl should be 
          // enabled or not. The environment variable equivalent is 
          // SSL. The default value is false.
          "ssl": false,

          // This is a path used to read the ssl cert file. The environment 
          // variable equivalent is CONVOY_SSL_CERT_FILE. If ssl is set to 
          // true, then this must be supplied. 
          "ssl_cert_file": "",

          // This is a path used to read the ssl key file. The environment 
          // variable equivalent is CONVOY_SSL_KEY_FILE. If ssl is set to 
          // true, then this must be supplied. 
          "ssl_key_file": "",

          // This is used to configure the port for the api server runs on. This 
          // config has no effect on the other components. The environment
          // variable equivalent is PORT.
          "port": 5005,

          // This is used to configure the port the worker server runs on. This 
          // config has no effect on the other components. The environment 
          // variable equivalent is WORKER_PORT.
          "worker_port": 5006,

          // This is used to configure the port the ingest server runs on. This 
          // config has no effect on the other components. The environment 
          // variable equivalent is INGEST_PORT.
          "ingest_port": 5007,

          // This is used to configure the port the socket server runs on. This 
          // config has no effect on the other components. The environment 
          // variable equivalent is SOCKET_PORT.
          "socket_port": 5008,

          // This is used to configure the forward proxy URL. This is must be set
          // on all workers if you want to configure a forward proxy. The 
          // environment variable equivalent is HTTP_PROXY.
          "http_proxy": ""
      }
  },

  // [required]
  // Redis configuration for your instance. Convoy uses redis for 
  // caching and enqueuing delivery.
  "redis": {

    // Redis port. The environment variable equivalent is
    // CONVOY_REDIS_PORT
    "port": 6379,

    // Redis host. The environment variable equivalent is
    // CONVOY_REDIS_HOST
    "host": "localhost",

    // Redis scheme. The environment variable equivalent is
    // CONVOY_REDIS_SCHEME. Redis sentinel is not currently supported.
    "scheme": "redis", 

    // Redis username. The environment variable equivalent is
    // CONVOY_REDIS_USERNAME.
    "username": "redis",

    // Redis password. The environment variable equivalent is
    // CONVOY_REDIS_PASSWORD.
    "password": "redis",

    // Redis database. The environment variable equivalent is 
    // CONVOY_REDIS_DATABASE. The default: 0
    "database": 0,

    // [optional]
    // Redis cluster addresses. The environment variable equivalent is 
    // CONVOY_REDIS_ADDRESSES. The value takes precedence over the 
    // other redis configuration in this object. The urls are fully
    // qualified domain names.
    "addresses": "{url}, {url}, ..."
  },

  // [optional]
  // This is used to tune the workers pool size in our workers. 
  // The environment variable equivalent is CONVOY_CONSUMER_POOL_SIZE.
  // The default value is 100.
  "consumer_pool_size": 100,

  // [optional]
  // This is enum flag used to enable access to experimental features. 
  // The only supported value as of this writing is experimental. 
  // The environment variable equivalent is CONVOY_FEATURE_FLAG.
  "feature_flag": "experimental",

  // [optional]
  // This is a boolean flag to configure profiling any Convoy component.
  // The environment variable equivalent is CONVOY_ENABLE_PROFILING. 
  // The default value is false.
  "enable_profiling": false,

  // [optional]
  // smtp configuration is used to configure an email backend to use in 
  // sending emails like notification emails, etc.
  "smtp": {

    // Specify the smtp provider. The environment variable equivalent is
    // CONVOY_SMTP_PROVIDER.  
		"provider": "sendgrid",

    // Specify the smtp URL. The environment variable equivalent is
    // CONVOY_SMTP_URL
		"url": "smtp.sendgrid.net",

    // Specify the smtp port. The environment variable equivalent is
    // CONVOY_SMTP_PORT
		"port": 2525,

    // Specify the smtp username. The environment variable equivalent is
    // CONVOY_SMTP_USERNAME
		"username": "apikey",

    // Specify the smtp password. The environment variable equivalent is 
    // CONVOY_SMTP_PASSWORD
		"password": "api-key-from-sendgrid",

    // Specify the smtp from email. The environment variable equivalent is 
    // CONVOY_SMTP_FROM
		"from": "[email protected]"
	}

  // [optional]
  // This is used to configure the logger for any Convoy component.
  "logger": {

    // This is used to configure the logging level. The supported values 
    // are: fatal, error, warn, info, debug. The environment variable
    // equivalent is CONVOY_LOGGER_LEVEL. The default value is error.
    "level": "debug"
  }

  // [optional]
  // This is used to configure how we generate and push traces to. While
  // it is an optional object, we highly recommend it to easily spot and 
  // fix production issues.
  "tracer": {

    // This is specifies the tracing backend to use, currently there are two 
    // supported in-built backends: otel, sentry. The environment variable
    // equivalent is CONVOY_TRACER_PROVIDER
    "type": "otel",

    // This is used to configure an otel tracing backend. If type above is set 
    // to otel, then the object needs to be fully configured.
    "otel": {

      // OTel trace generation sample rate. 
      "sample_rate": 1.0,

      // OTel backend URL. Only grpc ingestion urls are supported. 
      "collector_url": "",

      // Specifies if server certs should be verified or not.
      "insecure_skip_verify": true,

      // This is used to specify extra auth headers for specific backends. E.g.
      // some vendors require an api key authentication.
      "otel_auth": {

        // This is the request header key. E.g. Signoz-Api-Key. The environment
        // variable equivalent is CONVOY_OTEL_AUTH_HEADER_NAME.
        "header_name": "",

        // This is the request header value. The environment variable 
        // equivalent is CONVOY_OTEL_AUTH_HEADER_VALUE.
        "header_value": ""
      }
    },

    // This is used to configure the sentry tracing backend. If type above is set 
    // to sentry, then this object needs to be fully configured.
    "sentry": {

      // This is used to specify the sentry DSN. The environment variable equivalent
      // is CONVOY_SENTRY_DSN.
      "dsn": ""
    }
  },

  // [optional]
  // We use this to configure deleting events away from PostgreSQL. This config 
  // is optional, but if you're configuring retention policies on your project, 
  // then you need to supply it. 
  "storage_policy": {

    // The type can be either s3 or on_prem.
    "type": "s3",

    // If type above is set to s3, then this config needs to be supplied.
    "s3": {

      // We use this is prefix objects from this instance to S3. The
      // environment variable equivalent is CONVOY_STORAGE_AWS_PREFIX.
      "prefix": "",

      // S3 Buckect name. The environment variable equivalent is 
      // CONVOY_STORAGE_AWS_BUCKET.
      "bucket": "",

      // Bucket access key. The environment variable equivalent is 
      // CONVOY_STORAGE_AWS_ACCESS_KEY.
      "access_key": "",

      // Bucket secret key. The environment variable equivalent is 
      // CONVOY_STORAGE_AWS_SECRET_KEY.
      "secret_key": "",

      // Bucket region. The environment variable equivalent is 
      // CONVOY_STORAGE_AWS_REGION.
      "region": "",

      // auth session token. The environment variable equivalent is 
      // CONVOY_STORAGE_AWS_SESSION_TOKEN.
      "session_token": "",

      // The environment variable equivalent is CONVOY_STORAGE_AWS_ENDPOINT.
      "endpoint": ""
    },

    // If type above is set to on_prem, then this config needs to be supplied.
    "on_prem": {

      // This specifies the path on the machine where pruned events are stored. 
      // The environment variable equivalent is CONVOY_STORAGE_PREM_PATH.
      "path": ""
    }
  }

  // [optional]
  // This is used to configure authentication on your instance. The default values 
  // should be fine, except you want something more custom.
  "auth": {

    // This boolean flag is used to enable/disable registration on your
    // instance. The environment variable equivalent is CONVOY_SIGNUP_ENABLED.
    "is_signup_enabled": true,

    "jwt": {
      // This is a boolean flag to enable user authentication or not. 
      // The environment variable equivalent is CONVOY_JWT_REALM_ENABLED. 
      // The default value is true.
      "enabled": true,

      // This is used to generate JWT tokens for UI API access. The environment
      // variable equivalent is CONVOY_JWT_SECRET. 
      "secret": "",

      // This is used to determine how long a token is valid for in seconds. 
      // The environment variable equivalent is CONVOY_JWT_EXPIRY. 
      "expiry": 1800,

      // This is used to generate refresh JWT tokens. The environment 
      // variable equivalent is CONVOY_JWT_REFRESH_SECRET. 
      "refresh_secret": "",

      // This is used to determine how long a refresh token is valid for in seconds. 
      // The environment variable equivalent is CONVOY_JWT_REFRESH_EXPIRY. 
      "refresh_expiry": 3600
    },
    
    "native": {

      // This is a boolean flag to enable user authentication or not. 
      // The environment variable equivalent is CONVOY_NATIVE_REALM_ENABLED. 
      // The default value is true.
      "enabled": true
    }

  }
}